/ Hex Artifact Content
Login

Artifact cd10e4206b91c4bf03f121ab9209a14af0b48f14:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
1160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1170: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1180: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
11a0: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
11b0: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
11c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
11d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
11e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
11f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
1200: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1210: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1220: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1230: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1240: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1250: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1260: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1270: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1280: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1290: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
12a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
12b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
12c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
12d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
12e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
12f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
1300: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1310: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1320: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1330: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1340: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1350: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1360: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1370: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1380: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1390: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
13a0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
13b0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
13c0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
13d0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
13e0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
13f0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1400: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1410: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1420: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1430: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1440: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1450: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1460: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1470: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1480: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1490: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
14a0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
14c0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
14d0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14e0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
14f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
1500: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1510: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1520: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1530: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1540: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1550: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1560: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1570: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1580: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1590: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
15b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
15c0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
15d0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
15e0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
15f0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1600: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1610: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1620: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1630: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1640: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1650: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1660: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1670: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1680: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1690: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
16a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
16b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
16c0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
16d0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
16e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
16f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1700: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1710: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1720: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1730: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1740: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1750: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1760: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1770: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1780: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1790: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
17a0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
17b0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
17c0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
17d0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73  sion(void);.cons
17e0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
17f0: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  int sqlite3_libv
1810: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f  ersion_number(vo
1820: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1830: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1840: 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69  ibrary Compilati
1850: 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e  on Options Diagn
1860: 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ostics.**.** ^Th
1870: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1880: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66  eoption_used() f
1890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18a0: 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63  0 or 1 .** indic
18b0: 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68  ating whether th
18c0: 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69  e specified opti
18d0: 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61  on was defined a
18e0: 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  t .** compile ti
18f0: 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  me.  ^The SQLITE
1900: 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20  _ prefix may be 
1910: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1920: 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65   .** option name
1930: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74   passed to sqlit
1940: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1950: 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a  _used().  .**.**
1960: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1970: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1980: 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77  ) function allow
1990: 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f  s iterating.** o
19a0: 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20  ver the list of 
19b0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72  options that wer
19c0: 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d  e defined at com
19d0: 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20  pile time by.** 
19e0: 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d  returning the N-
19f0: 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  th compile time 
1a00: 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20  option string.  
1a10: 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  ^If N is out of 
1a20: 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65  range,.** sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20  get() returns a 
1a50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a60: 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20  The SQLITE_ .** 
1a70: 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65  prefix is omitte
1a80: 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e  d from any strin
1a90: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  gs returned by .
1aa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1ab0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a  leoption_get()..
1ac0: 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66  **.** ^Support f
1ad0: 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69  or the diagnosti
1ae0: 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69  c functions sqli
1af0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b00: 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20  n_used().** and 
1b10: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b20: 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20  ption_get() may 
1b30: 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70  be omitted by sp
1b40: 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a  ecifying the .**
1b50: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f   [SQLITE_OMIT_CO
1b60: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b70: 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d  S] option at com
1b80: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile time..**.**
1b90: 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66   See also: SQL f
1ba0: 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65  unctions [sqlite
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1bc0: 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1bd0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1be0: 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74  ion_get()] and t
1bf0: 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1c00: 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a  ons pragma]..*/.
1c10: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
1c20: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1c30: 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69  N_DIAGS.int sqli
1c40: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c50: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1c60: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f  r *zOptName);.co
1c70: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1c80: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1c90: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1ca0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1cb0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1cc0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1cd0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1ce0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cf0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1d00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1d10: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1d20: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1d30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1d40: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1d50: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1d60: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1d70: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1d80: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1d90: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1da0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1db0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1dc0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1dd0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1e00: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1e10: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1e20: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1e30: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1e40: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1e50: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e60: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1e70: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1e80: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1e90: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1ea0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1eb0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1ec0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1ed0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1ee0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1ef0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1f00: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1f10: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1f20: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1f30: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1f40: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1f50: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1f60: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1f70: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1f80: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1f90: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1fa0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1fb0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1fc0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1fd0: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1fe0: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1ff0: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2000: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
2010: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
2020: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
2030: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
2040: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
2050: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
2060: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2070: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
2080: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
2090: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
20a0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
20b0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20c0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
20d0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
20e0: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
20f0: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2110: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2130: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2140: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2150: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2160: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
2170: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
2180: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
2190: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
21a0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
21b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
21c0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
21d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
21e0: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
21f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2200: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2210: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2220: 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54  ERIALIZED].  ^(T
2230: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2240: 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  of the.** sqlite
2250: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
2260: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e  unction shows on
2270: 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ly the compile-t
2280: 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a  ime setting of.*
2290: 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c  * thread safety,
22a0: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
22b0: 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61  e changes to tha
22c0: 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62  t setting made b
22d0: 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  y.** sqlite3_con
22e0: 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20  fig(). In other 
22f0: 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72  words, the retur
2300: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
2310: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2320: 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65  ).** is unchange
2330: 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71  d by calls to sq
2340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29  lite3_config().)
2350: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ^.**.** See the 
2360: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2370: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2380: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2390: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  formation..*/.in
23a0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
23b0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
23c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
23d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23e0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
23f0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2400: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2410: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2420: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2430: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2440: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2450: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2460: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
2470: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
2480: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
2490: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
24a0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
24b0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
24c0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
24d0: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
24e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2520: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2530: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2540: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2550: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2560: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
2570: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
2580: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
2590: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
25a0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
25b0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
25c0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
25d0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25e0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
25f0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
2600: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
2610: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
2620: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
2630: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
2640: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
2650: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2660: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
2670: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
2680: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
2690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
26a0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
26b0: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
26c0: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
26d0: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
26e0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
26f0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
2700: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
2710: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
2720: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
2730: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
2740: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
2750: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
2760: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
2770: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
2780: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
2790: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
27a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
27b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
27c0: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
27d0: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
27e0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
27f0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
2800: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
2810: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
2820: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2830: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2840: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
2850: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
2860: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
2870: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
2880: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
2890: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
28b0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
28c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
28d0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
28e0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
28f0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
2900: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2910: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
2920: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2940: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2950: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2960: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2970: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
2980: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
2990: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
29a0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
29b0: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
29c0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
29d0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
29e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
29f0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
2a00: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
2a10: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
2a20: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2a30: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
2a40: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
2a50: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
2a60: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2a70: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
2a80: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
2a90: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
2aa0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
2ab0: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
2ac0: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
2ad0: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
2ae0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
2af0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
2b00: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
2b10: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
2b20: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
2b30: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
2b40: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
2b50: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
2b60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b70: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
2b80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
2b90: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
2ba0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
2bb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2bd0: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2be0: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2bf0: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2c00: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2c10: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2c20: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2c40: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2c50: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2c60: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2c70: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2c80: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2c90: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2ca0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2cb0: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2cc0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2cd0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2ce0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2cf0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2d00: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2d10: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2d20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2d30: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2d40: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2d50: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2d60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d70: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2d80: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2d90: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2da0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2db0: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2dc0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2dd0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2de0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2df0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2e00: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2e10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2e20: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2e30: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2e40: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2e50: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2e60: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2e70: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2e80: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2e90: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2ea0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2eb0: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2ec0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2ed0: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2ee0: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2ef0: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2f00: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2f10: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2f20: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2f30: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2f40: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2f50: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2f60: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2f70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2f80: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2f90: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2fa0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2fb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2fc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2fd0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2fe0: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2ff0: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
3000: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
3010: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
3020: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
3030: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
3040: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
3050: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
3060: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
3070: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
3080: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
3090: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
30a0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
30b0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
30c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
30d0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
30e0: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
30f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3100: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3110: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
3120: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3130: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
3140: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
3150: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
3160: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
3170: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3180: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3190: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
31a0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
31b0: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
31c0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31d0: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
31e0: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
31f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3200: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3210: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
3220: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
3230: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
3240: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
3250: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
3260: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
3270: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3280: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3290: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
32a0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
32b0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
32c0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
32d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
32e0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
32f0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3300: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3310: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
3320: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
3330: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
3340: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
3350: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
3360: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
3370: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3380: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3390: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
33a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
33b0: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
33c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
33d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
33e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3400: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3410: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3420: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3430: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3440: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3450: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3460: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
3470: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3480: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3490: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34a0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
34b0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
34c0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
34d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
34e0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
34f0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3500: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3510: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3520: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3530: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3540: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
3550: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
3560: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3570: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3580: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3590: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35a0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
35b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
35c0: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
35d0: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
35e0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
35f0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3600: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3610: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3620: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3630: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3640: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
3650: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
3660: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
3670: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
3680: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
3690: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36a0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
36b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36c0: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
36d0: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
36e0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
36f0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3700: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3710: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3720: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3730: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3740: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
3750: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
3760: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
3770: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
3780: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
3790: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
37b0: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
37c0: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
37d0: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
37e0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
37f0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3800: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3810: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3820: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3830: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3840: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
3850: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
3860: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
3870: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3890: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
38b0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
38c0: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
38d0: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
38e0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
38f0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3900: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3910: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3920: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3930: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3950: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
3960: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
3970: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
3980: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3990: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
39b0: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
39c0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
39d0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
39e0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
39f0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a00: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a20: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a30: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a40: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3a50: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3a60: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3a70: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a90: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3aa0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3ab0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3ac0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ad0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3ae0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3af0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b10: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b20: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b30: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b40: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3b50: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3b70: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3b80: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3b90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3ba0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3bb0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3bc0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3bd0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3be0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3bf0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c00: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c10: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c20: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3c50: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3c60: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3c70: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3c80: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3c90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3ca0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3cb0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3cc0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3cd0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3ce0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3cf0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d00: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d10: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d20: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d30: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d40: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3d50: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3d60: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3d70: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3d80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3d90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3da0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3db0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3dc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3dd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3de0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3df0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e00: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e10: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e20: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e30: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e40: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3e50: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3e60: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3e80: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3e90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3eb0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3ec0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3ed0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3ee0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3ef0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f00: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f10: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f30: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f40: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3f50: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3f60: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3f70: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3f80: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f90: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3fa0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3fd0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3fe0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ff0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4000: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4010: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4020: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4030: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4040: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
4050: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
4060: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4070: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4080: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4090: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <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 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
40c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
40d0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
40e0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
40f0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4100: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4110: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4120: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4130: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
4140: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
4150: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
4180: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4190: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
41a0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
41d0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
41e0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
41f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4200: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4210: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4220: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
4250: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
4260: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
4270: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
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 2f 2a 20 45 72 72 6f 72          /* Error
42a0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
42b0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
42c0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
42d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
42e0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
42f0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4300: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4310: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4320: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4330: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4340: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4350: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4360: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4370: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4380: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4390: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
43a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
43b0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
43c0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
43d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43e0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4410: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4420: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
4430: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4440: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4450: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4460: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
4470: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
4480: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
44a0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
44b0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
44c0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
44f0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4500: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
4530: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
4540: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4550: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4570: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4580: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4590: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
45b0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
45c0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
45d0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
45e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45f0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4600: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4610: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4630: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4640: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4650: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4660: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4670: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4680: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4690: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
46a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
46b0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
46c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
46d0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
46e0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
46f0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4710: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4720: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4730: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4740: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4760: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4770: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4780: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4790: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
47a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
47b0: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
47c0: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
47d0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
47e0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
47f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4800: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4810: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4820: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4830: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4840: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
4850: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
4860: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4870: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4880: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4890: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
48a0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
48b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
48c0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
48d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
48e0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4910: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4920: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4930: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4950: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4960: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4970: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
49a0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
49b0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
49d0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
49e0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
49f0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4a00: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4a10: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4a20: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4a30: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4a40: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4a50: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4a60: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4a70: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a90: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4aa0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4ab0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4ac0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4ad0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4ae0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4af0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4b00: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4b10: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4b20: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4b30: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4b40: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4b50: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4b60: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4b70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4b80: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4b90: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4ba0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4bc0: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4bd0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4be0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4c00: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4c10: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c20: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4c30: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4c50: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4c60: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4c70: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4c80: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4c90: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4ca0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4cb0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4cc0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4cd0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4ce0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4cf0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4d00: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4d10: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4d20: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4d30: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4d40: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4d50: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4d60: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4d70: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4d80: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4d90: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4da0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4db0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4dc0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4dd0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4de0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4df0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4e00: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4e10: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4e20: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4e30: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4e40: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4e50: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4e60: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4e70: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4e80: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4e90: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4ea0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4eb0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4ec0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4ed0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4ee0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4ef0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f00: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4f10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4f20: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4f30: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4f40: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4f50: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4f60: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4f70: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4f80: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4f90: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4fa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4fb0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4fc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4fd0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4fe0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ff0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5000: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5010: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5020: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5030: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5040: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5050: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5060: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5070: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
50c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50d0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
50e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50f0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5110: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5120: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5130: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5150: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5160: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5170: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5190: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51b0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
51c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51d0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
51e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51f0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5210: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5220: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5230: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5250: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5260: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5270: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5280: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5290: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
52a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52b0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52d0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
52e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52f0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5300: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5310: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5320: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5330: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5350: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5360: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5370: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5380: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5390: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
53a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53b0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
53c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53d0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
53e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53f0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5400: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5410: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5420: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5430: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5450: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5470: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5480: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5490: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
54a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54b0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
55e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55f0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
56d0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
56f0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5710: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5730: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5750: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5770: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5790: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
57a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57b0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
57e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57f0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5820: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5830: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5860: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5870: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5880: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
58a0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
58b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
58c0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
58e0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
58f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5900: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5910: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5920: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5930: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5940: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5950: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5960: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5970: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5980: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
59a0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
59b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
59c0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
59e0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
59f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a00: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a20: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5a30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a40: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5a50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5a70: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5a80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5aa0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ab0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5ac0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ad0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5ae0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5af0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b10: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b30: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5b40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5b50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5b80: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ba0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5bb0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5bc0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5bd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5be0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c00: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5c10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c20: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c40: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5c70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5c90: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5ca0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5cb0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5cc0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5cd0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ce0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5cf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d10: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5d20: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d30: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5d40: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5d50: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5d60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5d70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5d80: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5da0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5dc0: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5dd0: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5de0: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5df0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e00: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5e10: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5e20: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5e30: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5e40: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e50: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e60: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e80: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e90: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5ea0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5eb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5ec0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ee0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ef0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f30: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5f40: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f90: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5fe0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ff0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6020: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6030: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6050: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6060: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6070: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6090: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
60a0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
60b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60f0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6100: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6110: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6130: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6140: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6150: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6180: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6190: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61b0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
61c0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
61d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61f0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6200: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6210: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6240: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6250: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6270: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6280: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6290: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
62c0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
62d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62f0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6300: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6350: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6390: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
63a0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
63b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63e0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63f0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6400: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6410: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6430: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6440: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6460: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6470: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6480: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6490: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
64a0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
64b0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
64c0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
64d0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
64e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
64f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6500: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6510: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6520: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6530: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6540: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6550: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6560: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6570: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6580: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6590: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
65a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65b0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
65c0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
65d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6600: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6610: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6630: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6640: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6650: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6660: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6670: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6680: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6690: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
66a0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
66b0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
66c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
66e0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
66f0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6700: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6710: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6720: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6730: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6740: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6750: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6760: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6770: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6780: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6790: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
67a0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
67b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
67c0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
67d0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
67e0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
67f0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6810: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6820: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6830: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6840: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6850: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6860: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6870: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6880: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6890: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
68a0: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
68b0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
68c0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
68d0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
68e0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
68f0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6900: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6910: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6920: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6930: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6940: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
6950: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ag indicate that
6960: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
6970: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
6980: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
6990: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
69a0: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
69b0: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
69c0: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
69d0: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
69e0: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
69f0: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
6a00: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
6a10: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
6a20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a50: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a70: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6a80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ac0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ae0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6af0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b10: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b30: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b50: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6b60: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b80: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ba0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6bb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6bc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6bd0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6be0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6bf0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6c30: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6c40: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6c60: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6c70: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c90: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6ca0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6cb0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6cc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6cd0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6ce0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
6cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6d00: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
6d10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
6d20: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6d30: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6d40: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6d50: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6d60: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6d70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6d80: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6d90: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6da0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6db0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6dc0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6dd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6de0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e00: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6e10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6e20: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6e30: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6e40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6e50: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6e70: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e90: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6ea0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6eb0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6ec0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6ed0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ee0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6ef0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6f00: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6f10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6f20: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6f30: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6f40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6f50: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6f60: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6f70: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6f80: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6f90: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6fa0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6fb0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6fc0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6fd0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6fe0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6ff0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
7000: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
7010: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
7020: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
7030: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
7040: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
7050: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7060: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7070: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7080: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7090: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
70a0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
70b0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
70c0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
70d0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
70e0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
70f0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
7100: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
7110: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7120: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7130: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
7140: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
7150: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7160: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7180: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7190: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
71a0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
71b0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
71c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
71d0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
71e0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
71f0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
7200: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
7210: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
7220: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7230: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7240: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7250: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7260: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7270: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7280: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7290: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
72a0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
72b0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
72c0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
72d0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
72e0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
72f0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
7300: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
7310: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
7320: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
7330: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7340: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7350: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7360: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7370: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7380: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7390: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
73a0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
73b0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
73c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
73d0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
73e0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
73f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
7400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7420: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
7430: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7440: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7450: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7460: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7470: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7480: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7490: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
74a0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
74b0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
74c0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
74d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
74e0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
74f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
7500: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
7510: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
7520: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
7530: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7540: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7550: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7560: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7570: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7580: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7590: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
75a0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
75b0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
75c0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
75d0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
75e0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
75f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7600: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
7610: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7620: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
7630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7640: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7650: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7660: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7670: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7680: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7690: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
76a0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
76b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
76c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
76d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76e0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
76f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7700: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7710: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7720: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7730: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7740: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7750: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7770: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7780: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7790: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
77a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
77b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
77c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
77d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
77e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
77f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7810: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7820: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7830: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7840: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7850: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7860: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7870: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7880: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7890: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
78a0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
78b0: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
78c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
78d0: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
78e0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
78f0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7900: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7910: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7920: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7930: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7940: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7950: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7960: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7970: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7980: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
79a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
79b0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
79c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
79d0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
79e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
79f0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7a00: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7a10: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7a20: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7a30: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7a40: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7a50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7a60: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7a70: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7a80: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7a90: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7aa0: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7ab0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7ac0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7ad0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7ae0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7af0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7b00: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7b10: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7b20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7b30: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7b40: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7b50: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7b70: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7b90: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7ba0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7bb0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7bc0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7bd0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7be0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7bf0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7c00: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7c10: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7c20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7c30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7c40: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7c50: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7c60: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7c70: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7c80: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7c90: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7ca0: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7cb0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7cc0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7cd0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7ce0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7cf0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7d00: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7d10: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7d20: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7d30: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7d40: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7d50: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7d60: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7d70: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7d90: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7da0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7db0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7dc0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7dd0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7de0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7df0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7e00: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7e10: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7e20: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7e30: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7e40: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7e50: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7e60: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7e70: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7e80: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7e90: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7ea0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7eb0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7ec0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7ed0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ee0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7ef0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7f00: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7f10: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7f20: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7f30: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7f40: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7f50: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7f60: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7f70: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7f80: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7f90: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7fa0: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
7fb0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7fc0: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
7fd0: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7fe0: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7ff0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8000: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
8010: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
8020: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
8030: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
8040: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
8050: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8060: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8070: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8080: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8090: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
80a0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
80b0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
80c0: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
80d0: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
80e0: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
80f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
8100: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
8110: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
8120: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
8130: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
8140: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8150: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8160: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8170: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8180: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8190: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
81a0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
81b0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
81c0: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
81d0: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
81e0: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
81f0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
8200: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
8210: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
8220: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
8240: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8250: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8270: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
82a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
82c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
82e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
8300: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
8320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8330: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8340: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8350: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8360: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8380: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
8390: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
83b0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
83c0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
83d0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
83e0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8410: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
8420: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
8430: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
8440: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8450: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8460: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8470: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8480: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8490: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
84a0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
84b0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
84c0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
84d0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
84e0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
84f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8500: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8510: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8520: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8530: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8540: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8550: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8560: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8570: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8580: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8590: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
85a0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
85b0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
85c0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
85d0: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
85e0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
85f0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8600: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8610: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8620: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8630: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8640: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8650: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8660: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8670: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8680: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8690: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
86a0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
86b0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
86c0: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
86d0: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
86e0: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
86f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8700: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8710: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8740: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8750: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8770: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8780: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8790: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
87a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
87b0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
87d0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
87e0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
87f0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8800: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8820: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8830: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8840: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8850: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8860: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8880: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8890: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
88a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
88b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
88c0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
88d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
88e0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
88f0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8900: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8910: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8920: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8930: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8940: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8950: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8960: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8970: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8980: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8990: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
89a0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
89b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
89c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
89d0: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
89e0: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
89f0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8a00: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8a10: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8a20: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8a30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a40: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8a50: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8a60: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8a70: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8a80: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8a90: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8aa0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8ab0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8ac0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8ad0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8ae0: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8af0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8b00: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8b10: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8b20: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8b30: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8b40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b50: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8b60: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8b70: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8b80: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8b90: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8ba0: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8bb0: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
8bc0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
8bd0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
8be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
8bf0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
8c00: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
8c10: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
8c20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
8c30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8c40: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
8c50: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8c60: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8c70: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8c80: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8c90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8ca0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8cb0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8cc0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8cd0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8ce0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
8cf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8d00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
8d10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8d20: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8d40: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
8d50: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
8d60: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
8d70: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
8d80: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
8d90: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
8da0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
8db0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
8dc0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
8dd0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
8de0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8df0: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
8e00: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
8e10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8e20: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
8e30: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
8e40: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
8e50: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
8e60: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
8e70: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
8e80: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
8e90: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
8ea0: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
8eb0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
8ec0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
8ed0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8ee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8ef0: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8f10: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8f20: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8f30: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8f40: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8f50: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8f60: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8f70: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8f80: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8f90: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8fa0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8fb0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8fc0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8fd0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8fe0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8ff0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
9000: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
9010: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
9020: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
9030: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
9040: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
9050: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
9060: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9070: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9080: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9090: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
90a0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
90b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
90c0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
90d0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
90e0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
90f0: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
9100: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
9110: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
9120: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
9130: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
9140: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
9150: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9160: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9170: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9180: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9190: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
91a0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
91b0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
91c0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
91d0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
91e0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
91f0: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
9200: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
9210: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
9220: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
9230: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
9240: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
9250: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
9260: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
9270: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9280: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9290: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
92a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92b0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
92c0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
92d0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
92e0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
92f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9300: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9310: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9320: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9330: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9340: 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f  ee also [SQLITE_
9350: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9360: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9380: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9390: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93a0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
93b0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93c0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93d0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
93f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9400: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
9410: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69  journal file (ei
9420: 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c  ther.** the [rol
9430: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f  lback journal] o
9440: 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65  r the [write-ahe
9450: 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70  ad log]) for a p
9460: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9470: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9480: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9490: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
94a0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
94b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
94c0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
94d0: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
94e0: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
94f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9500: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
9510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
9520: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9530: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9540: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9550: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9560: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9570: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9580: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9590: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
95a0: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
95b0: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
95c0: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
95d0: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
95e0: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
95f0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
9600: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
9610: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9620: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9630: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9640: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9650: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9660: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9670: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9680: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9690: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
96a0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
96b0: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
96c0: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
96d0: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
96e0: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
96f0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
9700: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
9710: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
9720: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9730: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9740: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9750: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9760: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9770: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9780: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9790: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
97a0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
97b0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
97c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
97d0: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
97e0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
97f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9800: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9810: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
9820: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9830: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9840: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9850: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9860: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9880: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9890: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
98a0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
98b0: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
98c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
98d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
98e0: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
98f0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
9900: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
9910: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
9920: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9930: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9940: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9950: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9960: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9970: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9980: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9990: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
99a0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
99b0: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
99c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
99d0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
99e0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
99f0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9a00: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
9a10: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9a20: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9a30: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9a40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9a50: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9a60: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9a70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9a80: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9a90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9aa0: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9ab0: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9ac0: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9ad0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9ae0: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9af0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
9b00: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
9b10: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
9b20: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9b30: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9b40: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9b50: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9b60: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9b70: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9b80: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9b90: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9ba0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9bb0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9bc0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9bd0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9be0: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
9bf0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
9c00: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
9c10: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
9c20: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
9c30: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
9c40: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9c50: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9c60: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9c70: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9c80: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9c90: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9ca0: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9cb0: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9cc0: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9cd0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9cf0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9d00: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9d10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9d20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9d30: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9d40: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9d50: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9d60: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9d70: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9d80: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9d90: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9da0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9db0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9dc0: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9dd0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9de0: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9df0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9e00: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9e10: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9e20: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9e30: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9e40: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9e50: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9e60: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9e70: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9e80: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9e90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9ea0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9eb0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9ec0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9ed0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9ee0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9ef0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9f00: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9f10: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9f20: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9f30: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9f40: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9f50: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9f60: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9f70: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9f80: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9f90: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9fa0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9fb0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9fc0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9fd0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9fe0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9ff0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a000: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a010: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a020: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a030: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a040: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a050: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a060: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a070: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a080: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a090: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a0a0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a0b0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a0c0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a0d0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a0e0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a0f0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a100: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a110: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a120: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a130: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a140: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a160: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a170: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a180: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a190: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a1a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a1b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a1c0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a1d0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a1e0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a1f0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a200: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a210: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a220: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a230: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a240: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a250: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a270: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a280: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a290: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a2a0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a2b0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a2c0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a2d0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a2e0: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a2f0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a300: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a310: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a320: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a330: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a340: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a350: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a360: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a370: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a380: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a390: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a3a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a3b0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a3c0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a3d0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a3e0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a3f0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a400: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a410: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a420: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a430: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a440: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a450: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a460: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a470: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a480: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a490: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a4b0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a4d0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a4e0: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a4f0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a500: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a510: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a520: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a530: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a540: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a550: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a560: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a570: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a580: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a590: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a5a0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a5b0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a5c0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a5d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a5e0: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a5f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a600: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a610: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a620: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a630: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a640: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a650: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a660: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a670: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a680: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a690: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a6a0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a6b0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a6c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a6d0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a6e0: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a6f0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a700: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a710: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a720: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a730: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a740: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a750: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a760: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a770: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a780: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a790: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a7a0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a7b0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a7c0: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a7d0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a7e0: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a7f0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a800: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a810: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a820: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a830: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a840: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a850: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a860: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a870: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a880: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a890: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a8a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a8b0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
a8c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a8d0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a8e0: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
a8f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
a900: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
a910: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
a920: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
a930: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
a940: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a950: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
a960: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
a970: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
a980: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
a990: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
a9a0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
a9b0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
a9c0: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
a9d0: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
a9e0: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
a9f0: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
aa00: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
aa10: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
aa20: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
aa30: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
aa40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aa50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
aa60: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
aa70: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
aa80: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
aa90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aaa0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aab0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
aac0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
aad0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
aae0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
aaf0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
ab00: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
ab10: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
ab20: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
ab30: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
ab40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ab50: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ab60: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
ab70: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
ab80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
ab90: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
aba0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
abb0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
abc0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
abd0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
abe0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
abf0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
ac00: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
ac10: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
ac20: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
ac30: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
ac40: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
ac50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ac60: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ac70: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
ac80: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
ac90: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
aca0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
acb0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
acc0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
acd0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
ace0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
acf0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
ad00: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
ad10: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
ad20: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
ad30: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
ad40: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
ad50: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
ad60: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
ad70: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad80: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
ad90: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
ada0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
adb0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
adc0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
add0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
ade0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
adf0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
ae00: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ae10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
ae20: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
ae30: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
ae40: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
ae50: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
ae60: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
ae70: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
ae80: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
ae90: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
aea0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
aeb0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
aec0: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
aed0: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
aee0: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
aef0: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
af00: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
af10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
af20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
af30: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
af40: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
af50: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
af60: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
af70: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
af80: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
af90: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
afa0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
afb0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
afc0: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
afd0: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
afe0: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
aff0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b000: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b010: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b020: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b030: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b040: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b050: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b060: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b070: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b080: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b090: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b0a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b0b0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b0c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b0d0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b0e0: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b0f0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b100: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b110: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b120: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b130: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b140: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b150: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b160: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b170: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b180: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b190: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b1a0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b1b0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b1c0: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b1d0: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b1e0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b1f0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b200: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b210: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b220: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b230: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b240: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b250: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b270: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b280: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b290: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b2a0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b2b0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b2c0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b2d0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b2e0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b2f0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b300: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b310: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b320: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b330: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b340: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b350: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b370: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b380: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b390: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b3b0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b3c0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b3d0: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b3e0: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b3f0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b400: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b410: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b420: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b430: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b440: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b450: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b460: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b470: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b480: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b490: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b4a0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b4b0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
b4c0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
b4d0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
b4e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b4f0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
b500: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
b510: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
b520: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
b530: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
b540: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b550: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b560: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b570: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b580: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b590: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b5a0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b5b0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b5c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b5d0: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b5e0: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b5f0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b600: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b610: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b620: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b630: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b640: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b650: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b660: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b670: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b680: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b690: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b6a0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b6b0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b6c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b6d0: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b6e0: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b6f0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b700: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b710: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b720: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b730: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b740: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b750: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b760: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b770: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b780: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b790: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b7a0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b7b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b7c0: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b7e0: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b7f0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b800: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b810: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b820: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b830: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b840: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b850: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b860: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b870: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b880: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b890: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b8a0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b8b0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b8c0: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b8d0: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b8e0: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b8f0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b900: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b910: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b920: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b930: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b940: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b950: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b960: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b970: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b980: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b990: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b9a0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b9b0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b9c0: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b9d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b9e0: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b9f0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
ba00: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
ba10: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
ba20: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
ba30: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
ba40: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
ba50: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
ba60: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
ba70: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
ba80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ba90: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
baa0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bac0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
bad0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
bae0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
baf0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
bb00: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
bb10: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
bb20: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
bb30: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
bb40: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
bb50: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
bb60: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
bb70: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
bb80: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
bb90: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
bba0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
bbb0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
bbc0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
bbd0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bbe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
bbf0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bc00: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
bc10: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
bc20: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
bc30: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
bc40: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
bc50: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
bc60: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
bc70: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
bc80: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
bc90: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
bca0: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
bcb0: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
bcc0: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
bcd0: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
bce0: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
bcf0: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
bd00: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
bd10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
bd20: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
bd30: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
bd40: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
bd50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd60: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
bd70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bd80: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
bd90: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
bda0: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
bdb0: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
bdc0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
bdd0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
bde0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
bdf0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
be00: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
be10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
be20: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
be30: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
be40: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
be50: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
be60: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
be70: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
be80: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
be90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
bea0: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
beb0: 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  de.  .** </ul>.*
bec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bed0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
bee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf00: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
bf10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
bf20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf30: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
bf40: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
bf50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf60: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
bf80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf90: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
bfa0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
bfb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bfc0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
bfd0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
bfe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bff0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
c000: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
c010: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c020: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
c030: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
c040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c050: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
c060: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
c070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
c080: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
c090: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
c0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
c0b0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
c0c0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
c0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
c0e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
c0f0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
c100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
c110: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
c120: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
c130: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
c140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c150: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
c160: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
c170: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
c180: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
c190: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
c1a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
c1b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c1c0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
c1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1f0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
c200: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
c210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c220: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
c230: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
c240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c250: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
c260: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
c270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c280: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
c290: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
c2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c2c0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
c2d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
c2f0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
c300: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c310: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
c320: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
c330: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
c340: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
c350: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
c360: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
c370: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
c380: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
c390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
c3a0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
c3b0: 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65      28../* depre
c3c0: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c3d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c3e0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c3f0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c400: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c410: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c420: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c430: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c440: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c450: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c460: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c470: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c490: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c4a0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c4b0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c4c0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c4d0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c4e0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c4f0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c500: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c510: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c520: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c530: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c540: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c550: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c560: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c570: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c580: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c590: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c5a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c5b0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c5c0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c5d0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c5e0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c5f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c600: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c610: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c620: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c630: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c640: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c650: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c660: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c670: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c680: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c690: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c6a0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c6b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c6c0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c6d0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c6e0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c6f0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c700: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c710: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c720: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c730: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c740: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c750: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c760: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c770: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c780: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c790: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c7a0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c7b0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c7c0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c7d0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c7e0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c7f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c800: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c810: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c820: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c830: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c840: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c850: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c860: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c870: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c880: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c890: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c8a0: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c8b0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c8c0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c8d0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c8e0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c8f0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c900: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c910: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c920: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c930: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c940: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c950: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c960: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c970: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c980: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c990: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c9a0: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c9b0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c9c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c9d0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c9e0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c9f0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
ca00: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
ca10: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
ca20: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
ca30: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
ca40: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
ca50: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
ca60: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
ca70: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
ca80: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ca90: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
caa0: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
cab0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
cac0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
cad0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
cae0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
caf0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cb00: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
cb10: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cb20: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cb30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
cb40: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cb50: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
cb60: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cb70: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cb80: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cb90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cba0: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cbb0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cbc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cbd0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cbe0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cbf0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cc00: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
cc10: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
cc20: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
cc30: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
cc40: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
cc50: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
cc60: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
cc70: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
cc80: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
cc90: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
cca0: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
ccb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
ccc0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
ccd0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
cce0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
ccf0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
cd00: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
cd10: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
cd20: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
cd30: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
cd40: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
cd50: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
cd60: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
cd70: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
cd80: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
cd90: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
cda0: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
cdb0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
cdc0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
cdd0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
cde0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cdf0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
ce00: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
ce10: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
ce20: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
ce30: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
ce40: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
ce50: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
ce60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ce70: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
ce80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
ce90: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
cea0: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
ceb0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
cec0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
ced0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
cee0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cef0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
cf00: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
cf10: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
cf20: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
cf30: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
cf40: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
cf50: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
cf60: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cf70: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
cf80: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
cf90: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
cfa0: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
cfb0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
cfc0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cfd0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
cfe0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
cff0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d000: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d010: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d020: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d030: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d040: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d050: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d060: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d070: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d080: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d090: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d0a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d0b0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d0c0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d0d0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d0e0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d0f0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d100: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d110: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d120: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d130: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d140: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d150: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d160: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d170: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d180: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d190: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d1a0: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d1b0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d1c0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d1d0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d1e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d1f0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d200: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d210: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d220: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d230: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d240: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d250: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d260: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d270: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d280: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d290: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d2a0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d2b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d2c0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d2d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d2e0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d2f0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d300: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d310: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d320: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d330: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d340: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d350: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d360: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d370: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d380: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d390: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d3a0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d3b0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d3c0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d3d0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d3e0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d3f0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d400: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d410: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d420: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d430: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d440: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d450: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d460: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d470: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d480: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d490: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d4a0: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d4b0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d4c0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d4d0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d4e0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d4f0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d500: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d510: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d520: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d530: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d540: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d550: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d560: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d580: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d590: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d5a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d5b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d5c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d5d0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d5e0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d5f0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d600: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d610: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d620: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d630: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d640: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d650: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d660: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d670: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d680: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d690: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d6a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d6b0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d6c0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d6d0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d6e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d6f0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d700: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d710: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d720: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d730: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d740: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d750: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d760: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d770: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d780: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d790: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d7a0: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d7b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d7c0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d7d0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d7e0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d7f0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d800: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d810: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d820: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d830: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d840: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d850: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d860: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d870: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d880: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d890: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d8a0: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d8b0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d8c0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d8d0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d8e0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d8f0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d900: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d910: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d920: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d930: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d940: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d950: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d960: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d970: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d980: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d990: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d9a0: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d9b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d9c0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d9d0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d9e0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d9f0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
da00: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
da10: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
da20: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
da30: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
da40: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
da50: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
da60: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
da70: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
da80: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
da90: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
daa0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dab0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
dac0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
dad0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
dae0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
daf0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
db00: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
db10: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
db20: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
db30: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
db40: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
db50: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
db60: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
db70: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
db80: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
db90: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
dba0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
dbb0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
dbc0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
dbd0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
dbe0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
dbf0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
dc00: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
dc10: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
dc20: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
dc30: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
dc40: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
dc50: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
dc60: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
dc70: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
dc80: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
dc90: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
dca0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
dcb0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
dcc0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
dcd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
dce0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
dcf0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
dd00: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
dd10: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
dd20: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
dd30: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
dd40: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
dd50: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
dd60: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
dd70: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
dd80: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
dd90: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
dda0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
ddb0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
ddc0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
ddd0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
dde0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ddf0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
de00: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
de10: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
de20: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
de30: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
de40: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
de50: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
de60: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
de70: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
de80: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
de90: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
dea0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
deb0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
dec0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
ded0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
dee0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
def0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
df00: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
df10: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
df20: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
df30: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
df40: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
df50: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
df60: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
df70: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
df80: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
df90: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
dfa0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
dfb0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
dfc0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
dfd0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
dfe0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
dff0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e000: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e010: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e020: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e030: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e040: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e050: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e060: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e070: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e080: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e090: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e0a0: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e0b0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e0c0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e0d0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e0e0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e0f0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e100: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e110: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e120: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e130: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e140: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e150: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e160: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e170: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e180: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e190: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e1a0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e1b0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e1c0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e1d0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e1e0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e1f0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e200: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e210: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e220: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e230: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e240: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e250: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e260: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e270: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e280: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e290: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e2a0: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e2b0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e2c0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e2d0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e2e0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e2f0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e300: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e310: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e320: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e330: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e340: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e350: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e360: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e370: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e380: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e390: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e3a0: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e3b0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e3c0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e3d0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e3e0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e3f0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e400: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e410: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e420: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e430: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e440: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e450: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e460: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e470: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e480: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e490: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e4a0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e4b0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e4c0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e4d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e4e0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e4f0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e500: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e510: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e520: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e530: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e540: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e550: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e560: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e570: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e580: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e590: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e5a0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e5b0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e5c0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e5d0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e5e0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e5f0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e600: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e610: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e620: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e630: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e640: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e650: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e660: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e670: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e680: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e690: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e6a0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e6b0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e6c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e6d0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e6e0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e700: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e710: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e720: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
e730: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e740: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e750: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e760: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e770: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e780: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e790: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e7a0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e7b0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e7c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e7d0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e7e0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e7f0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e800: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e810: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e820: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e830: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e840: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e850: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e860: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e870: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e880: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e890: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e8a0: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e8b0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e8c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e8d0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e8e0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e8f0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e900: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e910: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e920: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e930: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e940: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e950: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e960: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e970: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e980: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e990: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e9a0: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e9b0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e9c0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e9d0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e9e0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e9f0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
ea00: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ea10: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ea20: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
ea30: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
ea40: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
ea50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
ea60: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ea70: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ea80: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ea90: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
eaa0: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
eab0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
eac0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
ead0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
eae0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
eaf0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
eb00: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
eb10: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
eb20: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
eb30: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
eb40: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
eb50: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
eb60: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
eb70: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb80: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
eb90: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
eba0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ebb0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ebc0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
ebd0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ebe0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ebf0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
ec00: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
ec10: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ec20: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
ec30: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
ec40: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
ec50: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
ec60: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
ec70: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
ec80: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
ec90: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
eca0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
ecb0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
ecc0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
ecd0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
ece0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
ecf0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
ed00: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ed10: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
ed20: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ed30: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ed40: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ed50: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ed60: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ed70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ed80: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ed90: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
eda0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
edb0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
edc0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
edd0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ede0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
edf0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ee00: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
ee10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ee20: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ee30: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ee40: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
ee50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ee60: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
ee70: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
ee80: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
ee90: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
eea0: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
eeb0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
eec0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
eed0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
eee0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
eef0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
ef00: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
ef10: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
ef20: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
ef30: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
ef40: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
ef50: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
ef60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ef70: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
ef80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ef90: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
efa0: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
efb0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
efc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
efd0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
efe0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
eff0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f000: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f010: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f020: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f040: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f060: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f070: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f080: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f090: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f0a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f0b0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f0c0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f0d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f0e0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f0f0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f100: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f110: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f120: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f130: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f140: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f150: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f160: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f170: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f180: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f190: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f1a0: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f1b0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f1c0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f1d0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f1e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f1f0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f200: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f210: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f220: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f230: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f240: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f250: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f260: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f270: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f280: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f290: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f2a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f2b0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f2c0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f2d0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f2e0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f2f0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f300: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f310: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f320: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f330: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f340: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f350: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f360: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f370: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f380: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f390: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f3a0: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f3b0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f3c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f3d0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f3e0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f3f0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f400: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f410: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f420: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f430: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f440: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f450: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f460: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f470: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f480: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f490: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f4a0: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f4b0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f4c0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f4d0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f4e0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f4f0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f500: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f510: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f520: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f530: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f540: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f560: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f570: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f580: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f590: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f5a0: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f5b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f5c0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f5d0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f5e0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f5f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f600: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f610: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f620: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f630: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f640: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f650: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f660: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f670: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f680: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f690: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f6a0: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f6b0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f6c0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f6d0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f6e0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f6f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f700: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f710: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f720: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f730: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f740: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f750: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f760: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f770: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f780: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f790: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f7a0: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f7b0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f7c0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f7d0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f7e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f7f0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f800: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f810: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f820: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f830: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f840: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f850: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f860: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f870: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f880: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f890: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f8a0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f8b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f8c0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f8d0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f8e0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f8f0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f900: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f910: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f920: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f930: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f940: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f950: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f960: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f970: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f980: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f990: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f9a0: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f9b0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f9c0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f9d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f9e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f9f0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fa00: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fa10: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fa20: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fa30: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fa40: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fa50: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fa60: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fa70: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fa80: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fa90: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
faa0: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fab0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
fac0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fad0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fae0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
faf0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fb00: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
fb10: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
fb30: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fb40: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
fb50: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
fb60: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
fb70: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
fb80: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
fb90: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
fba0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
fbb0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
fbc0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
fbd0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
fbe0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
fbf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fc00: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
fc10: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
fc20: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
fc30: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
fc40: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
fc50: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
fc60: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
fc70: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
fc80: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
fc90: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
fca0: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
fcb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fcc0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
fcd0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
fce0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
fcf0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
fd00: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
fd10: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
fd20: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
fd30: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
fd40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd50: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
fd60: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
fd70: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
fd80: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
fd90: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
fda0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
fdb0: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
fdc0: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
fdd0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
fde0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
fdf0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
fe00: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
fe10: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
fe20: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
fe30: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fe40: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
fe50: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
fe60: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
fe70: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
fe80: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
fe90: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fea0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
feb0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fed0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
fee0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fef0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
ff00: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
ff10: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
ff20: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
ff30: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
ff40: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
ff50: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
ff60: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
ff70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ff80: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
ff90: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
ffa0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
ffb0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
ffc0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
ffd0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
ffe0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
fff0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
10000 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10010 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10020 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10030 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10040 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10050 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10060 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10070 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10080 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
100a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
100b0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
100c0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
100d0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
100e0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
100f0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
10100 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10110 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10120 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10130 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10140 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10150 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10160 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10170 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10180 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10190 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
101a0 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
101b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
101c0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
101d0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
101e0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
101f0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
10200 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10210 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10220 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10230 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10240 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10250 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10260 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10270 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10280 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10290 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
102a0 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
102b0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
102c0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
102d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
102e0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
102f0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
10300 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10310 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10320 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10330 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10340 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10350 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10360 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10380 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10390 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
103a0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
103b0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
103c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
103d0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
103e0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
103f0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
10400 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10410 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10420 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10430 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10440 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10450 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10460 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10470 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10480 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10490 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
104a0 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
104b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
104c0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
104d0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
104e0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
104f0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
10500 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10520 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10530 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10540 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10550 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10560 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10570 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10580 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10590 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
105a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
105b0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
105c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
105d0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
105e0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
105f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
10600 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10610 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10620 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10630 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10640 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10650 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10660 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10670 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10680 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10690 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
106a0 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
106b0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
106c0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
106d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
106e0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
106f0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10700 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10710 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10720 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10730 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10740 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10750 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10760 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10770 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10780 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10790 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
107a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
107b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
107c0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
107d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
107e0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
107f0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10800 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10810 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10820 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10830 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10840 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10850 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10860 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10870 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10880 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10890 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
108a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
108b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
108c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
108d0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
108e0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
108f0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10900 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10910 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10920 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10930 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10940 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10950 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10960 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10970 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10980 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10990 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
109a0 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
109b0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
109c0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
109d0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
109e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
109f0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10a00 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10a10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10a20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10a30 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10a40 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10a50 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10a60 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10a70 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10a80 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10a90 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10aa0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10ab0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10ac0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10ad0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ae0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10af0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10b00 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10b10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10b20 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10b30 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10b40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10b50 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
10b60 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
10b70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10b80 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10b90 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10ba0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10bb0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10bc0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
10bd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10be0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10bf0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10c00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
10c10 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
10c20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
10c30 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
10c40 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10c50 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10c60 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
10c70 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10c80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10c90 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10ca0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10cb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10cc0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10cd0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10ce0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10cf0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10d10 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
10d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
10d30 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
10d40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10d50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
10d60 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
10d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10d80 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10d90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10da0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10db0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10dc0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10dd0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10df0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10e00 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10e10 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
10e20 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10e30 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10e40 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
10e50 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
10e60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
10e70 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10e80 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10e90 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10ea0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10eb0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10ec0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10ed0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10ee0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10ef0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10f00 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10f10 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
10f20 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10f30 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
10f40 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
10f50 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
10f60 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
10f70 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10f80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10f90 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10fa0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10fb0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10fc0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10fd0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10fe0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10ff0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
11000 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
11010 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11020 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11030 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11050 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11060 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11070 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11080 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11090 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
110a0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
110b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
110c0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
110d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
110e0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
110f0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
11100 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
11110 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11120 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11130 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11140 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11150 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11160 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11170 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11180 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11190 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
111a0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
111b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
111c0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
111d0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
111e0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
111f0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
11200 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11210 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11220 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11230 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11240 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11250 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11260 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11270 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11280 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11290 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
112a0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
112b0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
112c0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
112d0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
112e0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
112f0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
11300 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
11310 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11320 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11330 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11340 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11350 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11360 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11370 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11380 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11390 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
113a0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
113b0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
113c0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
113d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
113e0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
113f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
11400 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
11410 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11420 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11430 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11440 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11450 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11460 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11470 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11480 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11490 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
114a0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
114b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
114c0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
114d0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
114e0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
114f0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
11500 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11510 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11520 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11530 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11540 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11550 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11560 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11570 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11580 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11590 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
115a0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
115b0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
115c0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
115d0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
115e0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
115f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
11600 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11610 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11620 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11630 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11640 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11650 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11660 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11670 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11680 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11690 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
116a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
116b0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
116c0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
116d0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
116e0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
116f0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11700 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11710 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11720 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11730 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11740 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11750 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11760 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11770 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11780 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11790 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
117a0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
117b0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
117c0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
117d0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
117e0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
117f0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11800 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11810 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11820 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11830 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11840 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11850 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11860 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11870 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11880 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11890 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
118a0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
118b0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
118c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
118d0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
118e0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
118f0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11900 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11910 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11920 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11930 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11940 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11950 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11960 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11970 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11980 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11990 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
119a0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
119b0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
119c0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
119d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
119e0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
119f0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11a10 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11a20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11a30 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11a40 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11a50 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11a60 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11a70 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11a80 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11a90 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11aa0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11ab0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11ac0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11ad0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ae0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11af0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11b00 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11b10 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11b20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11b30 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11b40 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11b50 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11b60 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11b70 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11b80 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11b90 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11ba0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11bb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11bc0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11bd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11be0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11bf0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11c00 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11c10 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
11c20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
11c30 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11c40 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
11c50 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
11c60 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
11c70 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11c80 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11c90 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11ca0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11cb0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11cc0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11cd0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11ce0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11cf0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11d00 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11d10 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
11d20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
11d30 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
11d40 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
11d50 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
11d60 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11d70 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11d80 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11d90 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11da0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11db0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11dc0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11dd0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11de0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11df0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11e00 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11e10 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
11e20 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
11e30 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
11e40 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
11e50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
11e60 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
11e70 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11e80 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11e90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11ea0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11eb0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11ec0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11ed0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11ee0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11ef0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11f00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11f10 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
11f20 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
11f30 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
11f40 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
11f50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11f60 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
11f70 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11f80 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11f90 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11fa0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11fb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11fc0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11fd0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11fe0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11ff0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
12000 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
12010 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12020 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12030 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12040 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12050 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12060 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12070 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12080 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12090 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
120a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
120b0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
120c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
120d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
120e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
120f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12100 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12110 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12120 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12130 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12140 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12150 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12160 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12170 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12180 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12190 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
121a0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
121b0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
121c0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
121d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
121e0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
121f0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12200 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12210 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12220 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12230 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12240 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12250 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12260 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12270 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12280 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12290 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
122a0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
122b0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
122c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
122d0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
122e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
122f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12310 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12330 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12340 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12350 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12360 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12370 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12380 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12390 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
123a0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
123b0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
123c0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
123d0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
123e0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
123f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12400 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
12410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12420 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12430 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12440 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12460 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12470 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12480 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12490 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
124a0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
124b0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
124c0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
124d0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
124e0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
124f0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
12500 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12510 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12530 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12540 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12550 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12560 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12570 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12580 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12590 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
125a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
125b0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
125c0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
125d0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
125e0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
125f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12600 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12610 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12620 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12630 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12640 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12650 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12660 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12680 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
126a0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
126b0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
126c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
126d0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
126e0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
126f0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12700 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12710 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12720 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12730 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12740 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12750 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12760 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12780 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
127a0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
127b0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
127c0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
127d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
127e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
127f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12800 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12810 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12820 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12830 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12850 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12860 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12870 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12880 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12890 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
128a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
128b0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
128c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
128d0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
128e0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
128f0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12900 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12910 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12920 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12930 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12940 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12950 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12960 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12970 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12980 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12990 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
129a0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
129b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
129c0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
129d0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
129e0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
129f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a00 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12a10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12a20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12a30 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12a40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12a50 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12a60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12a80 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12a90 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12aa0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12ac0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12ad0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ae0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12af0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12b00 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12b10 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12b20 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12b30 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12b40 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12b50 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12b70 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12b80 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12b90 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12ba0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12bb0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12bc0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12bd0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12be0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12bf0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12c00 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12c10 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
12c20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12c30 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
12c40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12c50 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
12c60 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12c70 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12c80 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
12c90 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12ca0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
12cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12cc0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12cd0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12ce0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12cf0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
12d00 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12d10 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12d20 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12d30 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12d40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12d50 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
12d60 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12d70 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12d80 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12da0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12db0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12dc0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12dd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12de0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12df0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12e00 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12e10 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12e30 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12e40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12e50 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
12e60 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
12e70 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
12e80 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
12e90 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
12ea0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
12eb0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
12ec0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
12ed0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
12ee0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
12ef0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
12f00 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12f10 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
12f20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12f30 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
12f40 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
12f50 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
12f60 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
12f70 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
12f80 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
12f90 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12fa0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
12fb0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
12fc0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
12fd0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12fe0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
12ff0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
13000 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
13010 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13020 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13030 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13040 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13050 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13060 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13070 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13080 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13090 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
130a0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
130b0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
130c0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
130d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
130e0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
130f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13100 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
13110 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13120 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13130 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13140 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13150 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13160 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13170 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13180 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13190 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
131a0 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
131b0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
131c0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
131d0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
131e0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
131f0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
13200 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13210 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13220 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13230 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13240 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13250 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13260 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13270 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13280 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13290 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
132a0 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
132b0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
132c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
132d0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
132e0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
132f0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
13300 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13310 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13320 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13330 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13340 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13350 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13360 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13370 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13380 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13390 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
133a0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
133b0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
133c0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
133d0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
133e0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
133f0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13400 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13410 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13420 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13430 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13440 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13450 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13460 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13470 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13480 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13490 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
134a0 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
134c0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
134d0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
134e0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
134f0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
13500 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
13510 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13520 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13530 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13540 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13550 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13560 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13570 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13580 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13590 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
135a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
135b0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
135c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
135d0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
135e0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
135f0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
13600 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13610 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13620 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13630 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13640 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13650 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13660 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13680 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13690 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
136a0 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
136b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
136c0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
136d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
136e0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
136f0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13700 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13710 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13720 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13730 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13740 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13750 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13760 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13770 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13780 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13790 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
137a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
137b0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
137c0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
137d0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
137e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
137f0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13800 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13810 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13820 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13830 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13840 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13850 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13860 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13870 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13880 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13890 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
138a0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
138b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
138c0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
138d0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
138e0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
138f0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13900 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13910 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13920 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13930 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13940 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13950 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13960 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13970 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13980 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13990 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
139a0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
139b0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
139c0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
139d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
139e0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
139f0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13a00 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13a10 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13a20 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13a30 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13a40 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13a50 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13a60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13a70 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13a80 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13a90 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13aa0 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13ab0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13ac0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13ad0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ae0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13af0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13b00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13b10 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13b20 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13b30 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13b40 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13b50 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13b60 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13b70 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13b80 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13b90 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13ba0 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13bb0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13bc0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13bd0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13be0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13bf0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13c00 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
13c10 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
13c20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
13c30 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
13c40 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
13c50 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
13c60 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
13c70 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
13c80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13c90 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13cb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13cc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13cd0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
13ce0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13cf0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
13d00 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
13d10 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
13d20 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
13d30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13d40 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
13d50 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
13d60 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
13d70 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
13d80 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
13d90 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
13da0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
13db0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
13dc0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
13dd0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
13de0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
13df0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
13e00 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
13e10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
13e20 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
13e30 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
13e40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
13e50 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
13e60 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
13e70 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
13e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13e90 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
13ea0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
13eb0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
13ec0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13ed0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
13ee0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
13ef0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
13f00 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
13f10 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
13f20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
13f30 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
13f40 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
13f50 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
13f60 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
13f70 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13f80 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
13f90 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
13fa0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
13fb0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
13fc0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
13fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13fe0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
13ff0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
14000 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
14010 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14020 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14030 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14040 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14050 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14060 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14070 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14080 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14090 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
140a0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
140b0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
140c0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
140d0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
140e0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
140f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
14100 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14110 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14120 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14130 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14140 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14150 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14160 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14170 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14180 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14190 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
141b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
141c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
141d0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
141e0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
141f0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14200 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14210 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14220 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14230 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14240 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14250 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14260 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14270 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14280 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14290 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
142a0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
142b0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
142c0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
142d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
142e0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
142f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14300 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14310 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14320 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14330 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14340 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14350 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14360 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14370 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14380 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14390 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
143a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
143b0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
143c0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
143d0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
143e0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
143f0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
14400 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14410 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14420 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14430 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14440 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14450 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14460 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14480 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14490 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
144a0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
144b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
144c0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
144d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
144e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
144f0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14500 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14510 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14520 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14530 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14550 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14560 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14570 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14580 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14590 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
145a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
145b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
145c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
145d0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
145e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
145f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
14600 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
14610 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14620 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14630 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14640 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14650 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14660 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14670 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14680 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14690 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
146a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
146b0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
146c0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
146d0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
146e0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
146f0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14700 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14710 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14720 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14730 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14740 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14750 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14760 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14770 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14780 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14790 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
147a0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
147b0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
147c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
147d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
147e0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
147f0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14800 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14810 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14820 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14830 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14840 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14850 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14860 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14870 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14880 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14890 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
148a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
148b0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
148c0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
148d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
148e0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
148f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14900 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14910 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14920 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14930 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14940 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14950 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14960 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14970 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14980 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14990 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
149a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
149b0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
149c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
149d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
149e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
149f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14a00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14a10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14a20 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14a30 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14a40 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14a50 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14a60 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14a70 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14a80 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14a90 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14aa0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14ab0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14ac0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14ad0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ae0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14af0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14b00 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14b10 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14b20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14b30 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14b40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14b50 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14b60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14b80 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14b90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14ba0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14bb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14bc0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14bd0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14be0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14bf0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14c00 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
14c10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
14c20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
14c30 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14c40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c50 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
14c60 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
14c70 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
14c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
14c90 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
14ca0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
14cb0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
14cc0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
14cd0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
14ce0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
14cf0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
14d00 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
14d10 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
14d20 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
14d30 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
14d40 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
14d50 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
14d60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
14d70 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
14d80 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
14d90 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
14da0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
14db0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
14dc0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
14dd0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
14de0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
14df0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
14e00 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
14e10 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
14e20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
14e30 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
14e40 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
14e50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14e60 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
14e70 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
14e80 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
14e90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14ea0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
14eb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
14ec0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
14ed0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
14ee0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
14ef0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
14f00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
14f10 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14f20 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
14f30 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
14f40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
14f50 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
14f60 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
14f70 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
14f80 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
14f90 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
14fa0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
14fb0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
14fc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
14fd0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
14fe0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
14ff0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
15000 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15010 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15020 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15030 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15040 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15050 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15060 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15070 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15080 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15090 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
150a0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
150b0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
150c0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
150d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
150e0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
150f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
15100 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15110 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15140 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15150 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15160 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15170 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15180 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15190 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
151a0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
151b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
151c0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
151d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
151e0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
151f0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15200 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
15210 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15220 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15230 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15240 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15250 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15260 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15270 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15280 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15290 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
152a0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
152b0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
152c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
152d0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
152e0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
152f0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
15300 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15310 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15320 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15330 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15340 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15350 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15360 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15370 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15380 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
153a0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
153b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
153c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
153d0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
153e0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
153f0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15400 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15410 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15420 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15430 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15440 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15450 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15460 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15480 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15490 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
154a0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
154b0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
154c0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
154d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
154e0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
154f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
15500 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
15510 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15520 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15530 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15540 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15550 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15560 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15570 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15580 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15590 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
155a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
155b0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
155c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
155d0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
155e0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
155f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15600 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
15610 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15620 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15630 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15640 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15650 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15660 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15670 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15680 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15690 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
156a0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
156b0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
156c0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
156d0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
156e0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
156f0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15700 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15710 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15720 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15730 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15740 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15750 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15760 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15770 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15780 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15790 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
157a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
157b0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
157c0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
157d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
157e0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
157f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15800 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15810 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15820 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15830 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15840 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15850 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15860 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15870 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15880 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15890 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
158a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
158b0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
158c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
158d0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
158e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
158f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15900 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15910 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15920 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15930 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15940 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15950 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15960 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15970 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15980 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15990 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
159a0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
159b0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
159c0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
159d0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
159e0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
159f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15a00 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15a10 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15a20 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15a30 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15a40 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15a50 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15a60 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15a70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15a80 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15a90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15aa0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15ab0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15ac0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15ad0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ae0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15af0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15b00 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15b10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15b20 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15b30 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15b40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15b50 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15b70 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15b80 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15b90 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15ba0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15bb0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15bc0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15bd0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15be0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15bf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15c00 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
15c10 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
15c20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15c30 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
15c40 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
15c50 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
15c60 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
15c70 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
15c80 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
15c90 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
15ca0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
15cb0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
15cc0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
15cd0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
15ce0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15cf0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
15d00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15d10 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
15d20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
15d30 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
15d40 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
15d50 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
15d60 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
15d70 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
15d80 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
15d90 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
15da0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
15db0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
15dc0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
15dd0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15de0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
15df0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
15e00 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
15e10 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
15e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15e30 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
15e40 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
15e50 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
15e60 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
15e70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
15e80 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
15e90 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
15ea0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
15eb0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
15ec0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
15ed0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
15ee0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
15ef0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
15f00 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
15f10 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
15f20 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
15f30 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15f40 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
15f50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15f60 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
15f70 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
15f80 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
15f90 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
15fa0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
15fb0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
15fc0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
15fd0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
15fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15ff0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
16000 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16010 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16020 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16040 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16050 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16060 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16070 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16080 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16090 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
160a0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
160b0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
160c0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
160d0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
160e0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
160f0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
16100 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16110 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16120 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16130 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16140 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16150 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16160 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16170 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16180 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16190 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
161a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
161b0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
161c0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
161d0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
161e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
161f0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
16200 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
16210 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16220 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16230 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16240 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16250 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16260 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16270 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16280 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16290 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
162a0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
162b0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
162c0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
162d0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
162e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
162f0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
16300 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16310 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16320 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16330 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16340 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16350 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16360 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16370 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16380 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16390 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
163a0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
163b0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
163c0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
163d0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
163e0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
163f0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
16400 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
16410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16420 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16430 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16440 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16450 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16460 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16470 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16480 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16490 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
164a0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
164b0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
164c0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
164d0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
164e0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
164f0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
16500 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
16510 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16520 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16530 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16550 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16570 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16580 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
165a0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
165b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
165c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
165d0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
165e0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
165f0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
16600 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
16610 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16620 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16630 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16640 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16650 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16660 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16670 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16680 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16690 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
166a0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
166b0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
166c0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
166d0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
166e0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
166f0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16700 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16710 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16720 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16730 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16740 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16750 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16760 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16770 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16780 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16790 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
167a0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
167b0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
167c0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
167d0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
167e0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
167f0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16800 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16810 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16820 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16840 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16850 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16870 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16880 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16890 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
168a0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
168b0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
168c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
168d0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
168e0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
168f0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16910 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16920 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16930 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16950 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16960 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16970 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16990 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
169a0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
169b0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
169c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
169e0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
169f0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16a00 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16a10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16a20 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16a30 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16a50 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16a60 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16a70 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16a90 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16aa0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16ab0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16ac0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16ad0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ae0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16af0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16b00 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16b10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16b20 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16b30 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16b50 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16b60 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16b70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16b80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16b90 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16ba0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16bc0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16bd0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16be0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16bf0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16c00 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
16c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16c20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
16c30 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
16c40 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16c50 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
16c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16c70 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
16c80 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16c90 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16cb0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
16cc0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
16cd0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
16cf0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
16d00 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
16d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d20 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16d30 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
16d40 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
16d50 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
16d60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16d70 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16d80 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
16d90 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
16da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16db0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
16dc0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
16dd0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
16de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16df0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
16e00 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
16e10 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
16e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e30 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16e40 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
16e50 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
16e60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
16e70 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
16e80 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
16e90 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16ea0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
16eb0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16ec0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16ed0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16ee0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
16ef0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16f00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16f10 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16f20 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
16f30 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
16f40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16f50 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
16f60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
16f70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
16f80 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
16f90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
16fa0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
16fb0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16fc0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16fd0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16fe0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
16ff0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
17000 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17010 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17020 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17030 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17040 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17050 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17060 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17070 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17080 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17090 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
170a0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
170b0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
170c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
170d0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
170e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
170f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
17100 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17110 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17120 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17130 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17140 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17150 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17160 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17170 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17180 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17190 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
171a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
171b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
171c0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
171d0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
171e0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
171f0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17200 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17210 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17220 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17230 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17240 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17250 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17260 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17270 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17280 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17290 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
172a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
172b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
172c0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
172d0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
172e0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
172f0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
17300 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17310 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17320 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17330 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17340 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17350 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17360 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17370 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17380 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17390 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
173a0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
173b0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
173c0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
173d0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
173e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
173f0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
17400 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17410 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17420 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17430 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17440 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17450 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17460 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17470 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17480 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17490 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
174a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
174b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
174c0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
174d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
174e0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
174f0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
17500 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17510 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17520 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17530 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17540 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17550 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17560 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17570 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17580 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17590 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
175a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
175b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
175c0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
175d0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
175e0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
175f0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
17600 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17610 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17620 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17630 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17640 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17660 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17670 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17680 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17690 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
176a0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
176b0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
176c0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
176d0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
176e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
176f0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17700 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17710 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17720 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17730 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17740 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17750 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17760 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17770 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17780 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17790 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
177a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
177b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
177c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
177d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
177e0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
177f0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17800 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17810 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17820 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17830 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17840 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17850 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17860 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17870 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17880 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17890 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
178a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
178b0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
178c0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
178d0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
178e0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
178f0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17900 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17910 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17920 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17930 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17940 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17950 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17960 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17970 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17980 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17990 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
179a0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
179b0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
179c0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
179d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
179e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
179f0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17a00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17a10 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17a20 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17a30 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17a40 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17a50 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17a60 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17a70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17a80 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17a90 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17aa0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17ab0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17ac0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17ad0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ae0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17af0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17b00 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17b10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17b20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17b30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17b40 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17b50 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17b60 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17b70 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17b80 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17b90 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17ba0 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17bb0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17bc0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17bd0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17be0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17bf0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17c00 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17c10 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17c20 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
17c30 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
17c40 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17c50 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
17c60 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17c70 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
17c80 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
17c90 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
17ca0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17cb0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17cc0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17cd0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17ce0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17cf0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
17d00 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
17d10 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
17d20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17d30 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17d40 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17d50 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17d60 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17d70 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
17d80 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17d90 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17da0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17db0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17dc0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
17dd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17de0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17df0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17e00 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
17e10 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
17e20 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
17e30 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
17e40 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
17e50 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
17e60 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
17e70 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
17e80 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
17e90 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
17ea0 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
17eb0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
17ec0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
17ed0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
17ee0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
17ef0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
17f00 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17f10 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17f20 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
17f30 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
17f40 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
17f50 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
17f60 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
17f70 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
17f80 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
17f90 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
17fa0 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
17fb0 66 69 72 73 74 20 61 72 67 6d 65 6e 74 20 74 6f  first argment to
17fc0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
17fd0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
17fe0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
17ff0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18000 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
18010 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
18020 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
18030 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
18040 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
18050 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
18060 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
18070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18080 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18090 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
180a0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
180b0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
180c0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
180d0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
180e0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
180f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18100 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
18110 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18120 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
18130 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18140 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18150 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
18160 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
18170 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18180 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18190 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
181a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
181b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
181c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
181d0 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
181e0 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
181f0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
18200 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18210 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
18220 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
18230 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18250 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
18260 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
18270 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18290 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
182a0 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
182b0 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
182c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
182d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
182e0 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
182f0 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
18300 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
18310 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
18320 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
18330 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
18340 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18360 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
18370 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
18380 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
18390 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
183a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
183b0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
183c0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
183d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
183e0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
183f0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
18400 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
18410 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
18420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
18430 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
18440 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
18450 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
18460 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
18470 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
18480 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18490 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
184a0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
184b0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
184c0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
184d0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
184e0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
184f0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
18500 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
18510 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
18520 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
18530 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
18540 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
18550 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
18560 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
18570 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
18580 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
18590 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
185a0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
185b0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
185c0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
185d0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
185e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
185f0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
18600 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
18610 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
18620 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
18630 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
18640 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
18650 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
18660 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
18670 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
18680 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
18690 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
186a0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
186b0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
186c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
186d0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
186e0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
186f0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
18700 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
18710 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
18720 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
18730 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18740 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
18750 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
18760 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
18770 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18780 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
18790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
187a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
187b0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
187c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
187d0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
187e0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
187f0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
18800 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
18810 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
18820 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
18830 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
18840 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
18850 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
18860 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
18870 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
18880 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
18890 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
188a0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
188b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
188c0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
188d0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
188e0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
188f0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
18900 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
18910 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
18920 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
18930 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
18940 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
18950 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
18960 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
18970 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
18980 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
18990 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
189a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
189b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
189c0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
189d0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
189e0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
189f0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
18a00 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
18a10 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
18a20 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
18a30 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
18a40 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
18a50 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
18a60 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
18a70 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
18a80 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
18a90 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
18aa0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
18ab0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
18ac0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
18ad0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
18ae0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
18af0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
18b00 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
18b10 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
18b20 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
18b30 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
18b40 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
18b50 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
18b60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
18b70 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
18b80 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
18b90 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
18ba0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
18bb0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
18bc0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
18bd0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
18be0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
18bf0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
18c00 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
18c10 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
18c20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
18c30 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
18c40 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18c50 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18c60 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18c70 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
18c80 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
18c90 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
18ca0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
18cb0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
18cc0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
18cd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
18ce0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
18cf0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
18d00 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
18d10 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
18d20 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
18d30 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
18d40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18d50 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
18d60 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
18d70 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
18d80 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
18d90 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
18da0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
18db0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
18dc0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
18dd0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18de0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
18df0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
18e00 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
18e10 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
18e20 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
18e30 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
18e40 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
18e50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
18e60 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
18e70 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
18e80 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
18e90 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
18ea0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
18eb0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
18ec0 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
18ed0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18ee0 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
18ef0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
18f00 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
18f10 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
18f20 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18f30 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
18f40 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
18f50 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
18f60 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
18f70 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
18f80 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
18f90 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
18fa0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
18fb0 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
18fc0 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
18fd0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
18fe0 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
18ff0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19000 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19010 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19020 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
19030 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19040 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19050 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
19060 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
19070 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
19080 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
19090 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
190a0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
190b0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
190c0 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
190d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
190e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
190f0 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
19100 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19110 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
19120 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
19130 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
19140 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
19150 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
19160 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
19170 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
19180 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
19190 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
191a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
191b0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
191c0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
191d0 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
191e0 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
191f0 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
19200 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
19210 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
19220 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
19230 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
19240 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
19250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
19260 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
19270 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
19280 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
19290 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
192a0 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
192b0 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
192c0 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
192d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
192e0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
192f0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
19300 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
19310 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
19320 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
19330 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
19340 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
19350 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
19360 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
19370 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
19380 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
19390 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
193a0 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
193b0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
193c0 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
193d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
193e0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
193f0 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
19400 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
19410 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
19420 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
19430 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
19440 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
19450 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
19460 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
19470 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
19480 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
19490 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
194a0 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
194b0 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
194c0 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
194d0 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
194e0 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
194f0 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
19500 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19510 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
19520 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
19530 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
19540 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19550 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19560 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
19570 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
19580 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
19590 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
195a0 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
195b0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
195c0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
195d0 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
195e0 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
195f0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
19600 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
19610 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19620 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
19630 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
19640 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
19650 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
19660 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19670 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19680 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
19690 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
196a0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
196b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
196c0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
196d0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
196e0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
196f0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
19700 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19710 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19720 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
19730 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
19740 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
19750 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
19760 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
19770 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
19780 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
19790 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
197a0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
197b0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
197c0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
197d0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
197e0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
197f0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
19800 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
19810 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
19820 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19830 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
19840 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
19850 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
19860 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
19870 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
19880 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
19890 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
198a0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
198b0 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
198c0 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
198d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
198e0 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
198f0 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
19900 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
19910 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
19920 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
19930 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
19940 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
19950 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
19960 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19970 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
19980 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
19990 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
199a0 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
199b0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
199c0 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
199d0 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
199e0 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
199f0 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
19a00 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
19a10 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
19a20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
19a30 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
19a40 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
19a50 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
19a60 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
19a70 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19a80 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
19a90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
19aa0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19ab0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
19ac0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
19ad0 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
19ae0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19af0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19b00 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
19b10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
19b20 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
19b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
19b40 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
19b50 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
19b60 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
19b70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
19b80 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
19b90 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
19ba0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
19bb0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
19bc0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
19bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19be0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
19bf0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
19c00 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
19c10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
19c20 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
19c30 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
19c40 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
19c50 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
19c60 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
19c70 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
19c80 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
19c90 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
19ca0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
19cb0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
19cc0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
19cd0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
19ce0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
19cf0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
19d00 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
19d10 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
19d20 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
19d30 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
19d40 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
19d50 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
19d60 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
19d70 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
19d80 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
19d90 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
19da0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
19db0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
19dc0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
19dd0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
19de0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
19df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
19e00 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
19e10 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
19e20 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
19e30 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
19e40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
19e50 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
19e60 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
19e70 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
19e80 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
19e90 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
19ea0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
19eb0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
19ec0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
19ed0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
19ee0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
19ef0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
19f00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
19f10 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
19f20 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
19f30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
19f40 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
19f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
19f60 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
19f70 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
19f80 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
19f90 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
19fa0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
19fb0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
19fc0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
19fd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
19fe0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
19ff0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1a000 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1a010 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a020 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1a030 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1a040 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1a050 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1a060 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1a070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1a080 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1a090 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1a0a0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a0b0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1a0c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a0d0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1a0e0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1a0f0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1a100 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1a110 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1a120 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1a130 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1a140 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1a150 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1a160 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1a170 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a180 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a190 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1a1a0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1a1b0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1a1c0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1a1d0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a1e0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1a1f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1a200 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1a210 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1a220 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1a230 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1a240 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1a250 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1a260 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1a270 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1a280 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1a290 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a2a0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1a2b0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
1a2c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a2d0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
1a2e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1a2f0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
1a300 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
1a310 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
1a320 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
1a330 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a340 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1a350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1a360 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1a370 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1a380 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1a390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1a3a0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1a3b0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1a3c0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1a3d0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1a3e0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1a3f0 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1a400 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1a410 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1a420 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1a430 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1a440 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1a450 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1a460 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1a470 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1a480 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1a490 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1a4a0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1a4b0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1a4c0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1a4d0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1a4e0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1a4f0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1a500 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1a510 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1a520 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1a530 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1a540 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1a550 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1a560 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1a570 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1a580 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1a590 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1a5a0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1a5b0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1a5c0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1a5d0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1a5e0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1a5f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1a600 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1a610 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1a620 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1a630 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1a640 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1a650 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1a660 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1a670 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1a680 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1a690 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1a6a0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1a6b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1a6c0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1a6d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1a6e0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1a6f0 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1a700 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1a710 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1a720 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1a730 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1a740 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1a750 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1a760 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1a770 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1a780 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1a790 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1a7a0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1a7b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1a7c0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1a7d0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1a7e0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1a7f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1a800 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1a810 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1a820 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1a830 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1a840 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1a850 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1a860 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1a870 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1a880 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1a890 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1a8a0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1a8b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1a8c0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1a8d0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1a8e0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1a8f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1a900 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1a910 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1a920 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1a930 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1a940 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1a950 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1a960 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1a970 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1a980 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1a990 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1a9a0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1a9b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1a9c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1a9d0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1a9e0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1a9f0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1aa00 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1aa10 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1aa20 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1aa30 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1aa40 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1aa50 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1aa60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1aa70 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1aa80 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1aa90 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1aaa0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1aab0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1aac0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1aad0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1aae0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1aaf0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1ab00 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1ab10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1ab20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1ab30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ab40 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1ab50 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1ab60 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1ab70 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1ab80 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1ab90 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1aba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1abb0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1abc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1abd0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1abe0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1abf0 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1ac00 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1ac10 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1ac20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1ac30 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1ac40 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1ac50 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1ac60 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1ac70 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1ac80 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1ac90 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1aca0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1acb0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1acc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1acd0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1ace0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1acf0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1ad00 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1ad10 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1ad20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1ad30 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1ad40 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1ad50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1ad60 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1ad70 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1ad80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1ad90 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1ada0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1adb0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1adc0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1add0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1ade0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1adf0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1ae00 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1ae10 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1ae20 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1ae30 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1ae40 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1ae50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1ae60 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1ae70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ae80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1ae90 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1aea0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1aeb0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1aec0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1aed0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1aee0 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1aef0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1af00 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1af10 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1af20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1af30 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1af40 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1af50 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1af60 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1af70 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1af80 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1af90 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1afa0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1afb0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1afc0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1afd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1afe0 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1aff0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1b000 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1b010 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1b020 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1b030 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1b040 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1b050 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1b060 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1b070 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1b080 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1b090 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1b0a0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1b0b0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b0c0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1b0d0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1b0e0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1b0f0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1b100 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1b110 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1b120 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1b130 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b140 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1b150 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1b160 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1b170 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1b180 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1b190 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1b1a0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1b1b0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1b1c0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1b1d0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1b1e0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1b1f0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1b200 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1b210 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1b220 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1b230 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1b240 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1b250 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1b260 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1b270 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1b280 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1b290 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1b2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1b2b0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1b2c0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1b2d0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1b2e0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1b2f0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1b300 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1b310 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b320 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1b330 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1b340 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1b350 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1b360 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1b370 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1b380 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1b390 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1b3a0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1b3b0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1b3c0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1b3d0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1b3e0 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1b3f0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1b400 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1b410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1b420 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1b430 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1b440 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1b450 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1b460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1b470 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1b480 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1b490 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1b4a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b4b0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1b4c0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1b4d0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1b4e0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1b4f0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1b500 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1b510 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1b520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b530 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1b540 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1b550 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1b560 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1b570 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1b580 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1b590 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
1b5a0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
1b5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b5c0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1b5d0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1b5e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1b5f0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1b600 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1b610 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1b620 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1b630 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1b640 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1b650 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1b660 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1b670 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1b680 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1b690 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1b6a0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1b6b0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1b6c0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1b6d0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1b6e0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1b6f0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1b700 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1b710 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1b720 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1b730 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b740 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1b750 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1b760 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1b770 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1b780 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1b790 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1b7a0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1b7b0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1b7c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1b7d0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1b7e0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1b7f0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1b800 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1b810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1b820 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1b830 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1b840 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1b850 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1b860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1b870 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1b880 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1b890 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1b8a0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1b8b0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1b8c0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1b8d0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1b8e0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1b8f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1b900 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1b910 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1b920 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1b930 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1b940 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1b950 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1b960 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1b970 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1b980 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1b990 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1b9a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b9b0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1b9c0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1b9d0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1b9e0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1b9f0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1ba00 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1ba10 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1ba20 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1ba30 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ba40 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1ba50 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1ba60 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1ba70 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1ba80 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1ba90 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1baa0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1bab0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1bac0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1bad0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1bae0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1baf0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1bb00 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1bb10 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1bb20 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1bb30 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1bb40 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1bb50 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1bb60 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1bb70 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1bb80 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1bb90 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1bba0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1bbb0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1bbc0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1bbd0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1bbe0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1bbf0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1bc00 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1bc10 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1bc20 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1bc30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1bc40 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1bc50 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1bc60 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1bc70 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1bc80 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1bc90 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1bca0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1bcb0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1bcc0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1bcd0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1bce0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1bcf0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1bd00 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1bd10 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1bd20 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1bd30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1bd40 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1bd50 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1bd60 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1bd70 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1bd80 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1bd90 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1bda0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1bdb0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1bdc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1bdd0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1bde0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1bdf0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1be00 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1be10 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1be20 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1be30 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1be40 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1be50 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1be60 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1be70 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1be80 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1be90 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1bea0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1beb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1bec0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1bed0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1bee0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1bef0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1bf00 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1bf10 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1bf20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bf30 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1bf40 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1bf50 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1bf60 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1bf70 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1bf80 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1bf90 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1bfa0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1bfb0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1bfc0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1bfd0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1bfe0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1bff0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1c000 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c010 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c020 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1c030 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c040 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1c050 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1c060 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1c070 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1c080 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c090 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1c0a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c0b0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1c0c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c0d0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1c0e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c0f0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1c100 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1c110 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1c120 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1c130 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1c140 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1c150 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c160 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1c170 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1c180 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1c190 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1c1a0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1c1b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1c1c0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1c1d0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1c1e0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1c1f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1c200 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1c210 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1c220 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1c230 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1c240 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1c250 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1c260 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1c270 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1c280 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1c290 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1c2a0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1c2b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1c2c0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1c2d0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1c2e0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1c2f0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1c300 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1c310 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c320 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1c330 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c340 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1c350 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1c360 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1c370 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1c380 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1c390 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1c3a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1c3b0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1c3c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1c3d0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1c3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1c3f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1c400 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1c410 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1c420 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1c430 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1c440 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1c450 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1c460 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1c470 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1c480 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1c490 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1c4a0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1c4b0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1c4c0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1c4d0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1c4e0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1c4f0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1c500 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1c510 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1c520 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1c530 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1c540 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1c550 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1c560 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1c570 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1c580 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1c590 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1c5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1c5b0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1c5c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1c5d0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1c5e0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1c5f0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1c600 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1c610 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1c620 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1c630 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1c640 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1c650 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1c660 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1c670 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1c680 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1c690 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1c6a0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1c6b0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1c6c0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1c6d0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1c6e0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1c6f0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1c700 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1c710 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1c720 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1c730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c740 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1c750 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1c760 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1c770 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1c780 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1c790 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1c7a0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1c7b0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1c7c0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1c7d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c7e0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1c7f0 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1c800 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20   K&R formatting 
1c810 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73  options,.** plus
1c820 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1c830 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1c840 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20  rmats, detailed 
1c850 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74  below..** Note t
1c860 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20  hat some of the 
1c870 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72  more obscure for
1c880 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1c890 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43  from recent.** C
1c8a0 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72  -library standar
1c8b0 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66  ds are omitted f
1c8c0 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  rom this impleme
1c8d0 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ntation..**.** ^
1c8e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1c8f0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1c900 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1c910 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1c920 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1c930 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1c940 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1c950 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1c960 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1c970 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1c980 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1c990 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1c9a0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1c9b0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1c9c0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1c9d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1c9e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c9f0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1ca00 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1ca10 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1ca20 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1ca30 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1ca40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1ca50 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1ca60 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1ca70 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1ca80 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1ca90 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1caa0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1cab0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1cac0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1cad0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1cae0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1caf0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1cb00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1cb10 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1cb20 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1cb30 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1cb40 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1cb50 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1cb60 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1cb70 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1cb80 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1cb90 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1cba0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1cbb0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1cbc0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1cbd0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1cbe0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1cbf0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1cc00 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1cc10 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1cc20 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1cc30 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1cc40 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1cc50 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1cc60 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1cc70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1cc80 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1cc90 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1cca0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1ccb0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1ccc0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1ccd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1cce0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1ccf0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1cd00 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1cd10 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1cd20 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1cd30 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1cd40 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1cd50 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1cd60 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1cd70 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1cd80 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1cd90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1cda0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1cdb0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1cdc0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1cdd0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1cde0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1cdf0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1ce00 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1ce10 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1ce20 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1ce30 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1ce40 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1ce50 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1ce60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1ce70 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1ce80 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1ce90 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1cea0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1ceb0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1cec0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1ced0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1cee0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1cef0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1cf00 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1cf10 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1cf20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1cf30 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1cf40 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1cf50 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1cf60 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1cf70 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1cf80 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61  q", "%Q", "%w" a
1cf90 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1cfa0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1cfb0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1cfc0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1cfd0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1cfe0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1cff0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1d000 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1d010 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1d020 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1d030 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1d040 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1d050 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1d060 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1d070 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1d080 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1d090 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1d0a0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1d0b0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1d0c0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1d0d0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1d0e0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1d0f0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1d100 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1d110 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1d120 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d130 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d140 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1d150 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1d160 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1d170 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d180 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1d190 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1d1a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d1b0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1d1c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d1d0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1d1e0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1d1f0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1d200 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1d210 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1d220 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1d230 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1d240 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1d250 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1d260 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d270 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1d280 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1d290 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1d2a0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1d2b0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1d2c0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1d2d0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1d2e0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1d2f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d300 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1d310 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1d320 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1d330 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1d340 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d350 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1d360 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1d370 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1d380 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1d390 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1d3a0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1d3b0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1d3c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d3d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1d3e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1d3f0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1d400 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1d410 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1d420 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1d430 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1d440 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1d450 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1d460 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1d470 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1d480 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1d490 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1d4a0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1d4b0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1d4c0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1d4d0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1d4e0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1d4f0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1d500 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1d510 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1d520 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1d530 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1d540 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1d550 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1d560 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1d570 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1d580 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1d590 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1d5a0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1d5b0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1d5c0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1d5d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d5e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1d5f0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1d600 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1d610 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1d620 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1d630 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1d640 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1d650 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1d660 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1d670 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d680 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1d690 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1d6a0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1d6b0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1d6c0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1d6d0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1d6e0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1d6f0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1d700 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1d710 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1d720 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65  g option is like
1d730 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61   "%q" except tha
1d740 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a  t it expects to.
1d750 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  ** be contained 
1d760 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75  within double-qu
1d770 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20  otes instead of 
1d780 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61  single quotes, a
1d790 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73  nd it.** escapes
1d7a0 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74   the double-quot
1d7b0 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74  e character inst
1d7c0 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c  ead of the singl
1d7d0 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61  e-quote.** chara
1d7e0 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77  cter.)^  The "%w
1d7f0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1d800 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ion is intended 
1d810 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72  for safely inser
1d820 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e  ting.** table an
1d830 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69  d column names i
1d840 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65  nto a constructe
1d850 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  d SQL statement.
1d860 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1d870 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1d880 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1d890 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1d8a0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1d8b0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1d8c0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1d8d0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1d8e0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1d8f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d900 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1d910 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1d920 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1d930 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1d940 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1d950 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1d960 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1d970 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1d980 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1d990 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1d9a0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1d9b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1d9c0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1d9d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1d9e0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1d9f0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1da00 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1da10 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1da20 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1da30 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1da40 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1da50 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1da60 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1da70 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1da80 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1da90 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1daa0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1dab0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1dac0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1dad0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1dae0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1daf0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1db00 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1db10 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1db20 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1db30 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1db40 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1db50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1db60 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1db70 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1db80 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1db90 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1dba0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1dbb0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1dbc0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1dbd0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1dbe0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1dbf0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1dc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1dc10 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1dc20 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1dc30 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1dc40 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1dc50 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1dc60 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1dc70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1dc80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1dc90 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1dca0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1dcb0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1dcc0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1dcd0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1dce0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1dcf0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1dd00 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1dd10 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1dd20 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1dd30 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1dd40 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1dd50 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1dd60 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1dd70 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1dd80 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1dd90 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1dda0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1ddb0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1ddc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1ddd0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1dde0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1ddf0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1de00 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1de10 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1de20 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1de30 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1de40 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1de50 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1de60 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1de70 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1de80 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1de90 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1dea0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1deb0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1dec0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1ded0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1dee0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1def0 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1df00 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1df10 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1df20 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1df30 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1df40 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1df50 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1df60 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1df70 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1df80 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1df90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1dfa0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1dfb0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1dfc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1dfd0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1dfe0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1dff0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1e000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e010 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1e020 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1e030 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1e040 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1e050 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1e060 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e070 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1e080 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1e090 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1e0a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1e0b0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1e0c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e0d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1e0e0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1e0f0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1e100 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1e110 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1e120 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1e130 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1e140 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e150 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1e160 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1e170 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1e180 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1e190 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1e1a0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1e1b0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1e1c0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1e1d0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1e1e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1e1f0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1e200 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1e210 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1e220 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1e230 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1e240 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1e250 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1e260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e270 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1e280 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1e290 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1e2a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e2b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1e2c0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1e2d0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1e2e0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1e2f0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1e300 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1e310 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1e320 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1e330 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1e340 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e350 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1e360 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1e370 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1e380 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1e390 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1e3a0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1e3b0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1e3c0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1e3d0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1e3e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e3f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1e400 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1e410 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1e420 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1e430 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1e440 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1e450 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1e460 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1e470 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1e480 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1e490 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1e4a0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1e4b0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1e4c0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1e4d0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1e4e0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1e4f0 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1e500 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e510 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1e520 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1e530 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1e540 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1e550 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1e560 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1e570 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1e580 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1e590 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1e5a0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1e5b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e5c0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1e5d0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1e5e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1e5f0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1e600 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1e610 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1e620 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1e630 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1e640 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1e650 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1e660 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1e670 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1e680 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1e690 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1e6a0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1e6b0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1e6c0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1e6d0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1e6e0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1e6f0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1e700 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1e710 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1e720 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1e730 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1e740 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1e750 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1e760 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1e770 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1e780 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1e790 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1e7a0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1e7b0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1e7c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1e7d0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1e7e0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1e7f0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1e800 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1e810 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1e820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1e830 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1e840 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1e850 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1e860 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1e870 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1e880 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1e890 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1e8a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1e8b0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1e8c0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1e8d0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1e8e0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1e8f0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1e900 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1e910 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1e920 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1e930 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1e940 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1e950 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1e960 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1e970 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1e980 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1e990 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1e9a0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1e9b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1e9c0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1e9d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1e9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1e9f0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1ea00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ea10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1ea20 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1ea30 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1ea40 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1ea50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1ea60 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1ea70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1ea80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1ea90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1eaa0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1eab0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1eac0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1ead0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1eae0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1eaf0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1eb00 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1eb10 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1eb20 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1eb30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1eb40 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1eb50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1eb60 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1eb70 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1eb80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1eb90 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1eba0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1ebb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1ebc0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1ebd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1ebe0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1ebf0 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1ec00 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1ec10 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1ec20 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1ec30 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1ec40 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1ec50 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1ec60 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1ec70 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1ec80 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1ec90 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1eca0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1ecb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1ecc0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1ecd0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1ece0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1ecf0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1ed00 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1ed10 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1ed20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1ed30 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1ed40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1ed50 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1ed60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1ed70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1ed80 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1ed90 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1eda0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1edb0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1edc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1edd0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1ede0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1edf0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1ee00 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1ee10 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ee20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1ee30 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1ee40 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1ee50 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1ee60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1ee70 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1ee80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1ee90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1eea0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1eeb0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1eec0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1eed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1eee0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1eef0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1ef00 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1ef10 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1ef20 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1ef30 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1ef40 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1ef50 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1ef60 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1ef70 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1ef80 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1ef90 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1efa0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1efb0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1efc0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1efd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1efe0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1eff0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f000 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1f010 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1f020 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1f030 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f040 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1f050 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1f060 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1f070 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1f080 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1f090 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1f0a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1f0b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f0c0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1f0d0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1f0e0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1f0f0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1f100 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1f110 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1f120 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1f130 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1f140 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1f150 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1f160 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1f170 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1f180 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1f190 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1f1a0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1f1b0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1f1c0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1f1d0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1f1e0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1f1f0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1f200 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1f210 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1f220 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1f230 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1f240 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1f250 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1f260 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1f270 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1f280 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1f290 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1f2a0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1f2b0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1f2c0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1f2d0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1f2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f2f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1f300 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1f310 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1f320 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1f330 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1f340 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1f350 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1f360 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1f370 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1f380 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1f390 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1f3a0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1f3b0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1f3c0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1f3d0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1f3e0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1f3f0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1f400 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1f410 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1f420 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1f430 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1f440 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1f450 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1f460 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1f470 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1f480 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1f490 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1f4a0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1f4b0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1f4c0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1f4d0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1f4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1f4f0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1f500 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1f510 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
1f520 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1f530 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1f540 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1f550 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1f560 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1f570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f580 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1f590 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1f5a0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1f5b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f5c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1f5d0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1f5e0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1f5f0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1f600 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1f610 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1f620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f630 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1f640 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1f650 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1f660 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1f670 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1f680 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1f690 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1f6a0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1f6b0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1f6c0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1f6d0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1f6e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f6f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f700 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1f710 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1f720 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1f730 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f740 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1f750 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1f760 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1f770 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1f780 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1f790 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1f7a0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1f7b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f7c0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1f7d0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1f7e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1f7f0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1f800 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1f810 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1f820 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1f830 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1f840 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f850 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1f860 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1f870 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1f880 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1f890 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1f8a0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1f8b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f8c0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1f8d0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1f8e0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1f8f0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1f900 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1f910 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1f920 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1f930 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1f940 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1f950 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1f960 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1f970 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1f980 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1f990 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1f9a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1f9b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1f9c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1f9d0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1f9e0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1f9f0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1fa00 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1fa10 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1fa20 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1fa30 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1fa40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1fa50 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1fa60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fa70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1fa80 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1fa90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1faa0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1fab0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1fac0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1fad0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1fae0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1faf0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1fb00 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1fb10 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1fb20 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1fb30 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1fb40 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1fb50 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1fb60 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1fb70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1fb80 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1fb90 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1fba0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1fbb0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1fbc0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1fbd0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1fbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1fbf0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1fc00 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1fc10 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1fc20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1fc30 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1fc40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1fc50 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1fc60 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1fc70 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1fc80 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1fc90 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1fca0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1fcb0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1fcc0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1fcd0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1fce0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1fcf0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1fd00 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1fd10 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1fd20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1fd30 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1fd40 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1fd50 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1fd60 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1fd70 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1fd80 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1fd90 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fda0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1fdb0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1fdc0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1fdd0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1fde0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1fdf0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1fe00 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1fe10 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1fe20 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1fe30 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1fe40 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1fe50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fe60 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1fe70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1fe80 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1fe90 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1fea0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1feb0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1fec0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1fed0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1fee0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1fef0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1ff00 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1ff10 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1ff20 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1ff30 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1ff40 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1ff50 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1ff60 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1ff70 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1ff80 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1ff90 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1ffa0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1ffb0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1ffc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ffd0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1ffe0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1fff0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
20000 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
20010 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
20020 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
20030 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
20040 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
20050 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
20060 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
20070 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
20080 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
20090 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
200a0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
200b0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
200c0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
200d0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
200e0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
200f0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
20100 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
20110 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
20120 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
20130 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
20140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
20150 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
20160 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
20170 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
20180 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
20190 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
201a0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
201b0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
201c0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
201d0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
201e0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
201f0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
20200 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
20210 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
20220 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
20230 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
20240 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
20250 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
20260 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
20270 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
20280 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
20290 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
202a0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
202b0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
202c0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
202d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
202e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
202f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20300 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20320 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20330 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20340 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
20350 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
20360 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20370 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20380 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
20390 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
203a0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
203b0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
203c0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
203d0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
203e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
203f0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
20400 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
20410 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
20420 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
20430 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
20440 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
20450 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
20460 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
20470 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
20480 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
20490 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
204a0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
204b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
204c0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
204d0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
204e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
204f0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
20500 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20510 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20520 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
20530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20540 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20550 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
20560 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
20570 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
20580 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
20590 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
205a0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
205b0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
205c0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
205d0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
205e0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
205f0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
20600 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
20610 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
20620 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
20630 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
20640 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20650 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
20660 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
20670 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
20680 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
20690 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
206a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
206b0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
206c0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
206d0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
206e0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
206f0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
20700 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
20710 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
20720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
20730 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
20740 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
20750 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
20760 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
20770 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
20780 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
20790 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
207a0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
207b0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
207c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
207d0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
207e0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
207f0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
20800 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
20810 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
20820 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
20830 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
20840 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
20850 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
20860 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
20870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
20880 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
20890 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
208a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
208b0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
208c0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
208d0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
208e0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
208f0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
20900 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
20910 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
20920 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
20930 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
20940 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
20950 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
20960 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
20970 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20980 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
20990 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
209a0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
209b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
209c0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
209d0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
209e0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
209f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
20a00 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
20a10 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
20a20 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
20a30 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
20a40 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
20a50 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
20a60 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
20a70 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
20a80 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
20a90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
20aa0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
20ab0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
20ac0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
20ad0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
20ae0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
20af0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
20b00 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
20b10 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
20b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
20b30 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
20b40 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
20b50 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
20b60 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
20b70 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
20b80 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
20b90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
20ba0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
20bb0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
20bc0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
20bd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
20be0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
20bf0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
20c00 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
20c10 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
20c20 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
20c30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
20c40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20c50 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
20c60 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
20c70 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
20c80 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
20c90 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
20ca0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
20cb0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
20cc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
20cd0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
20ce0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
20cf0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
20d00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20d10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20d20 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
20d30 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
20d40 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
20d50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20d60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
20d70 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
20d80 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
20d90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20da0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20db0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
20dc0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20dd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20de0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20df0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20e00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
20e10 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20e20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20e30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20e40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
20e50 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
20e60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20e70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20e80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20e90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
20ea0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
20eb0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
20ec0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20ed0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20ee0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20ef0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
20f00 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20f10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20f30 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
20f40 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
20f50 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20f60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20f80 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
20f90 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
20fa0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
20fb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20fd0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
20fe0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
20ff0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21000 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21020 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
21030 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
21040 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21050 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21070 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
21080 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
21090 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
210a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
210b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
210c0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
210d0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
210e0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
210f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21110 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
21120 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
21130 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21140 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21150 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21160 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
21170 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
21180 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21190 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
211a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
211b0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
211c0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
211d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
211e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
211f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21200 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
21210 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
21220 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21230 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21240 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
21250 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
21260 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21270 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21280 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21290 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
212a0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
212b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
212c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
212d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
212e0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
212f0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
21300 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
21310 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
21320 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
21330 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
21340 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
21350 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21360 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21370 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21380 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
21390 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
213a0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
213b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
213c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
213d0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
213e0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
213f0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
21400 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21420 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
21430 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
21440 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21450 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21470 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
21480 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
21490 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
214a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
214b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
214c0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
214d0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
214e0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
214f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21510 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
21520 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
21530 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
21540 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
21560 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
21570 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
21580 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
21590 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
215a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
215b0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
215c0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
215d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
215e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
215f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21600 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
21610 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
21620 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
21630 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
21640 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21650 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
21660 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
21670 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
21680 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21690 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
216a0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
216b0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
216c0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
216d0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
216e0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
216f0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
21700 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
21710 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
21720 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
21730 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
21740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
21750 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
21760 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
21770 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
21780 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
21790 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
217a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
217b0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
217c0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
217d0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
217e0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
217f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
21800 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
21810 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20  are deprecated. 
21820 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
21830 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74  _trace_v2()] int
21840 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61  erface.** instea
21850 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65  d of the routine
21860 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65  s described here
21870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
21880 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
21890 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
218a0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
218b0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
218c0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
218d0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
218e0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
218f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
21900 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
21910 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
21920 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
21930 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
21940 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
21950 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21960 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
21970 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
21980 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
21990 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
219a0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
219b0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
219c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
219d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
219e0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
219f0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
21a00 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
21a10 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
21a20 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
21a30 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
21a40 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
21a50 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
21a60 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
21a70 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
21a80 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
21a90 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
21aa0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
21ab0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
21ac0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
21ad0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
21ae0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
21af0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
21b00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
21b10 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
21b20 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
21b30 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
21b40 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
21b50 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
21b60 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
21b70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21b80 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
21b90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
21ba0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
21bb0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
21bc0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
21bd0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
21be0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
21bf0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
21c00 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
21c10 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
21c20 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
21c30 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
21c40 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
21c50 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
21c60 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
21c70 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
21c80 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
21c90 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
21ca0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
21cb0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
21cc0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
21cd0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
21ce0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
21cf0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
21d00 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
21d10 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
21d20 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
21d30 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
21d40 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
21d50 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
21d60 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
21d70 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
21d80 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
21d90 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
21da0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
21db0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
21dc0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
21dd0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
21de0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
21df0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
21e00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
21e10 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
21e20 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
21e30 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
21e40 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
21e50 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
21e60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
21e70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
21e80 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
21e90 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
21ea0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
21eb0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
21ec0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
21ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
21ee0 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
21ef0 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
21f00 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
21f10 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
21f20 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
21f30 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
21f40 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
21f50 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
21f60 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
21f70 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
21f80 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64  ogic.  The third
21f90 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
21fa0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
21fb0 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64  2()] is an OR-ed
21fc0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
21fd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a  one or more of.*
21fe0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
21ff0 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65  constants.  ^The
22000 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22010 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
22020 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20  lback.** is one 
22030 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22040 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
22050 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f  * New tracing co
22060 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61  nstants may be a
22070 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
22080 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  eleases..**.** ^
22090 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
220a0 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65   has four argume
220b0 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54  nts: xCallback(T
220c0 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
220d0 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
220e0 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ne of the intege
220f0 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f  r type codes abo
22100 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ve..** ^The C ar
22110 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
22120 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
22130 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22140 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  n as the.** four
22150 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
22160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22170 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ()]..** The P an
22180 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
22190 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
221a0 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
221b0 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c   on T..**.** <dl
221c0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  >.** [[SQLITE_TR
221d0 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53  ACE_STMT]] <dt>S
221e0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
221f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22200 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
22210 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  MT callback is i
22220 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72  nvoked when a pr
22230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22240 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73  .** first begins
22250 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73   running and pos
22260 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74  sibly at other t
22270 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a  imes during the.
22280 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  ** execution of 
22290 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
222a0 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20  tement, such as 
222b0 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20  at the start of 
222c0 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20  each.** trigger 
222d0 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65  subprogram. ^The
222e0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
222f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
22300 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22310 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20  tement]. ^The X 
22320 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22330 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
22340 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  g which.** is th
22350 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c  e unexpanded SQL
22360 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65   text of the pre
22370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
22380 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
22390 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  t .** that indic
223a0 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74  ates the invocat
223b0 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72  ion of a trigger
223c0 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  .  ^The callback
223d0 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20   can compute.** 
223e0 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68  the same text th
223f0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65  at would have be
22400 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  en returned by t
22410 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
22420 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69  e3_trace()].** i
22430 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e  nterface by usin
22440 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  g the X argument
22450 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77   when X begins w
22460 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76  ith "--" and inv
22470 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  oking.** [sqlite
22480 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
22490 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  )] otherwise..**
224a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
224b0 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74  CE_PROFILE]] <dt
224c0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  >SQLITE_TRACE_PR
224d0 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OFILE</dt>.** <d
224e0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
224f0 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
22500 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70  ack provides app
22510 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73  roximately the s
22520 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ame.** informati
22530 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65  on as is provide
22540 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
22550 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c  3_profile()] cal
22560 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50  lback..** ^The P
22570 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22580 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
22590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
225a0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
225b0 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
225c0 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65  to a 64-bit inte
225d0 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65  ger which is the
225e0 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a   estimated of.**
225f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
22600 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74  anosecond that t
22610 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22620 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22630 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  n..** ^The SQLIT
22640 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
22650 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22660 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61  ked when the sta
22670 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22680 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22690 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e  TRACE_ROW]] <dt>
226a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
226b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
226c0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
226d0 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  W callback is in
226e0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
226f0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
22700 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73  tement generates
22710 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
22720 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54   result.  .** ^T
22730 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
22740 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22750 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22760 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
22770 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  * X argument is 
22780 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  unused..**.** [[
22790 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
227a0 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
227b0 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e  TRACE_CLOSE</dt>
227c0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
227d0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63  TE_TRACE_CLOSE c
227e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
227f0 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ed when a databa
22800 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
22810 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65   closes..** ^The
22820 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22830 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
22840 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22850 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  tion] object.** 
22860 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65  and the X argume
22870 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
22880 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
22890 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  e SQLITE_TRACE_S
228a0 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23  TMT       0x01.#
228b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
228c0 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30  ACE_PROFILE    0
228d0 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x02.#define SQLI
228e0 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20  TE_TRACE_ROW    
228f0 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65      0x04.#define
22900 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
22910 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f  OSE      0x08../
22920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
22930 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a  QL Trace Hook.**
22940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
22950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22960 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
22970 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
22980 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63  registers a trac
22990 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
229a0 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74  nction X against
229b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
229c0 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20  ction] D, using 
229d0 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a  property mask M.
229e0 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70  ** and context p
229f0 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74  ointer P.  ^If t
22a00 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
22a10 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74  .** NULL or if t
22a20 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72  he M mask is zer
22a30 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20  o, then tracing 
22a40 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68  is disabled.  Th
22a50 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20  e.** M argument 
22a60 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69  should be the bi
22a70 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62  twise OR-ed comb
22a80 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65  ination of.** ze
22a90 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49  ro or more [SQLI
22aa0 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61  TE_TRACE] consta
22ab0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  nts..**.** ^Each
22ac0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
22ad0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22ae0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
22af0 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20  _v2() overrides 
22b00 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e  .** (cancels) an
22b10 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
22b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22b30 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
22b40 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e_v2()..**.** ^T
22b50 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
22b60 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
22b70 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65  r any of the eve
22b80 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62  nts identified b
22b90 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63  y .** mask M occ
22ba0 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65  ur.  ^The intege
22bb0 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  r return value f
22bc0 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  rom the callback
22bd0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a   is currently.**
22be0 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68   ignored, though
22bf0 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65   this may change
22c00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
22c10 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a  ses.  Callback.*
22c20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
22c30 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
22c40 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66  zero to ensure f
22c50 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c  uture compatibil
22c60 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ity..**.** ^A tr
22c70 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
22c80 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75  invoked with fou
22c90 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c  r arguments: cal
22ca0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
22cb0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
22cc0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
22cd0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a   [SQLITE_TRACE].
22ce0 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20  ** constants to 
22cf0 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65  indicate why the
22d00 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e   callback was in
22d10 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43  voked..** ^The C
22d20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
22d30 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
22d40 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54  xt pointer..** T
22d50 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
22d60 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
22d70 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
22d80 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
22d90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22da0 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72  trace_v2() inter
22db0 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
22dc0 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20   to replace the 
22dd0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
22de0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72  aces [sqlite3_tr
22df0 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ace()] and [sqli
22e00 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20  te3_profile()], 
22e10 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a  both of which.**
22e20 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
22e30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22e40 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69  trace_v2(.  sqli
22e50 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64  te3*,.  unsigned
22e60 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78   uMask,.  int(*x
22e70 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e  Callback)(unsign
22e80 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76  ed,void*,void*,v
22e90 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  oid*),.  void *p
22ea0 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Ctx.);../*.** CA
22eb0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
22ec0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
22ed0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
22ee0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
22ef0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
22f00 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
22f10 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
22f20 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
22f30 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
22f40 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
22f50 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
22f60 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
22f70 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
22f80 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
22f90 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
22fa0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
22fb0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
22fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22fd0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
22fe0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
22ff0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23000 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23010 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23020 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23030 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23040 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
23050 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
23060 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
23070 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
23080 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
23090 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
230a0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
230b0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
230c0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
230d0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
230e0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
230f0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23100 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23110 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23120 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23130 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23140 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
23150 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
23160 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
23170 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
23180 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
23190 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
231a0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
231b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
231c0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
231d0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
231e0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
231f0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23200 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23210 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23220 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23230 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23240 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
23250 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
23260 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
23270 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
23280 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
23290 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
232a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
232b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
232c0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
232d0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
232e0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
232f0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23300 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23310 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23320 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23330 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23340 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23350 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
23360 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
23370 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
23380 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
23390 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
233a0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
233b0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
233c0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
233d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
233e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
233f0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23400 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23420 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23430 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23440 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
23450 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
23460 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
23470 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
23480 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
23490 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
234a0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
234b0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
234c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
234d0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
234e0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
234f0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
23500 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
23510 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
23520 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
23530 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23540 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
23550 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
23560 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
23570 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
23580 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23590 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
235a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
235b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
235c0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
235d0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
235e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
235f0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
23600 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
23610 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
23620 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
23630 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
23640 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
23650 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
23660 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
23670 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
23680 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
23690 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
236a0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
236b0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
236c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
236d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
236e0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
236f0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
23700 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23710 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
23720 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
23730 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
23740 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
23750 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
23760 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
23770 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
23780 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
23790 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
237a0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
237b0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
237c0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
237d0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
237e0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
237f0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
23800 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
23810 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
23820 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23830 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
23840 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
23850 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
23860 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
23870 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
23880 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23890 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
238a0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
238b0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
238c0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
238d0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
238e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
238f0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
23900 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
23910 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
23920 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
23930 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
23940 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
23950 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
23960 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
23970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23980 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
23990 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
239a0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
239b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
239c0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
239d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
239e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
239f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23a00 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
23a10 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
23a20 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
23a30 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
23a40 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
23a50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
23a60 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
23a70 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
23a80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23a90 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
23aa0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
23ab0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
23ac0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
23ad0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
23ae0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
23af0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
23b00 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
23b10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
23b20 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
23b30 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
23b40 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
23b50 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
23b60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
23b70 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
23b80 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
23b90 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
23ba0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
23bb0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
23bc0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
23bd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
23be0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
23bf0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
23c00 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
23c10 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
23c20 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
23c30 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23c40 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
23c50 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
23c60 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
23c70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
23c80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23c90 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
23ca0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
23cb0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
23cc0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
23cd0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
23ce0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
23cf0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
23d00 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
23d10 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
23d20 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
23d30 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
23d40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
23d50 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
23d60 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
23d70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
23d80 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
23d90 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
23da0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
23db0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
23dc0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
23dd0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
23de0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
23df0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
23e00 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
23e10 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
23e20 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
23e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23e40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
23e50 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
23e60 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
23e70 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
23e80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
23e90 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
23ea0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
23eb0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
23ec0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
23ed0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
23ee0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
23ef0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
23f00 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
23f10 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
23f20 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
23f30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
23f40 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23f50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
23f60 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
23f70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23f80 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
23f90 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
23fa0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
23fb0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
23fc0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
23fd0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
23fe0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
23ff0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24000 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
24010 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24020 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
24030 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
24040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24050 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
24060 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24070 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24080 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
24090 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
240a0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
240b0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
240c0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
240d0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
240e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
240f0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
24100 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24110 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
24120 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
24130 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
24140 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
24150 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24160 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
24170 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
24180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
24190 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
241a0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
241b0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
241c0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
241d0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
241e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
241f0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
24200 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
24210 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
24220 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
24230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
24240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
24250 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24260 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24270 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
24280 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
24290 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
242a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
242b0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
242c0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
242d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
242e0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
242f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24300 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
24310 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
24320 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
24330 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
24340 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
24350 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
24360 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
24370 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
24380 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
24390 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
243a0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
243b0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
243c0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
243d0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
243e0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
243f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24400 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
24410 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
24420 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
24430 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
24440 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
24450 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
24460 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
24470 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
24480 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
24490 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
244a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
244b0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
244c0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
244d0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
244e0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
244f0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
24500 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
24510 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
24520 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
24530 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
24540 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
24550 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
24560 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
24570 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
24580 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
24590 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
245a0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
245b0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
245c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
245d0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
245e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
245f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
24600 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
24610 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
24620 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
24630 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
24640 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
24650 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
24660 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
24670 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
24680 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24690 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
246a0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
246b0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
246c0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
246d0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
246e0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
246f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
24700 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24710 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
24720 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
24730 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
24740 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
24750 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
24760 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
24770 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
24780 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24790 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
247a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
247b0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
247c0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
247d0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
247e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
247f0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
24800 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
24810 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
24820 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
24830 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
24840 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
24850 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
24860 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
24870 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
24880 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
24890 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
248a0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
248b0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
248c0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
248d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
248e0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
248f0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
24900 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
24910 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
24920 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
24930 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
24940 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
24950 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
24960 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
24970 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
24980 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
24990 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
249a0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
249b0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
249c0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
249d0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
249e0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
249f0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
24a00 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
24a10 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
24a20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
24a30 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
24a40 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
24a50 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
24a60 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
24a70 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
24a80 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
24a90 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
24aa0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
24ab0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
24ac0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
24ad0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
24ae0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
24af0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
24b00 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
24b10 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
24b20 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
24b30 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
24b40 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
24b50 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
24b60 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
24b70 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
24b80 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
24b90 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
24ba0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
24bb0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
24bc0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
24bd0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
24be0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
24bf0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
24c00 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
24c10 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
24c20 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
24c30 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
24c40 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
24c50 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
24c60 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
24c70 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
24c80 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
24c90 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
24ca0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
24cb0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
24cc0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
24cd0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
24ce0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
24cf0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
24d00 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
24d10 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
24d20 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
24d30 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
24d40 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
24d50 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
24d60 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
24d70 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
24d80 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
24d90 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
24da0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
24db0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
24dc0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
24dd0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
24de0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
24df0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
24e00 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
24e10 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
24e20 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
24e30 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
24e40 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
24e50 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
24e60 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
24e70 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
24e80 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
24e90 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
24ea0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
24eb0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
24ec0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
24ed0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
24ee0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24ef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24f00 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
24f10 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
24f20 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
24f30 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
24f40 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
24f50 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
24f60 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
24f70 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
24f80 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
24f90 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
24fa0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
24fb0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
24fc0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
24fd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24fe0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
24ff0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
25000 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
25010 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
25020 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
25030 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
25040 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
25050 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
25060 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25070 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
25080 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
25090 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
250a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
250b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
250c0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
250d0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
250e0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
250f0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
25100 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
25110 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
25120 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
25130 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
25140 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
25150 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25160 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
25170 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25180 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
25190 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
251a0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
251b0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
251c0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
251d0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
251e0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
251f0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
25200 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
25210 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
25220 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
25230 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
25240 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
25250 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
25260 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
25270 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
25280 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
25290 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
252a0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
252b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
252c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
252d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
252e0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
252f0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
25300 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
25310 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
25320 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
25330 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
25340 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
25350 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
25360 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
25370 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25380 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
25390 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
253a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
253b0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
253c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
253d0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
253e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
253f0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
25400 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
25410 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
25420 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
25430 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
25440 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
25450 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
25460 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
25470 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
25480 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
25490 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
254a0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
254b0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
254c0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
254d0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
254e0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
254f0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
25500 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
25510 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
25520 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
25530 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
25540 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
25550 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
25560 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
25570 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
25580 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
25590 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
255a0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
255b0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
255c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
255d0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
255e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
255f0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
25600 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
25610 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
25620 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
25630 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
25640 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
25650 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
25660 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
25670 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
25680 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
25690 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
256a0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
256b0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
256c0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
256d0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
256e0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
256f0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
25700 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
25710 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
25720 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
25730 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
25740 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
25750 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
25760 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
25770 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
25780 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
25790 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
257a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
257b0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
257c0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
257d0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
257e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
257f0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
25800 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
25810 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
25820 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
25830 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
25840 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
25850 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
25860 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
25870 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
25880 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
25890 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
258a0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
258b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
258c0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
258d0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
258e0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
258f0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
25900 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
25910 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
25920 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
25930 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
25940 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
25950 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
25960 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
25970 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
25980 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
25990 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
259a0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
259b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
259c0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
259d0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
259e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
259f0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
25a00 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
25a10 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
25a20 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
25a30 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
25a40 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
25a50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
25a60 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
25a70 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
25a80 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
25a90 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
25aa0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
25ab0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
25ac0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
25ad0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
25ae0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
25af0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
25b00 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
25b10 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
25b20 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
25b30 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
25b40 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
25b50 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
25b60 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
25b70 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
25b80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25b90 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
25ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
25bb0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
25bc0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
25bd0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
25be0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
25bf0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25c00 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
25c10 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
25c20 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
25c30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
25c40 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
25c50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25c60 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
25c70 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
25c80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
25c90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
25ca0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
25cb0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
25cc0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
25cd0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
25ce0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
25cf0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
25d00 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
25d10 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
25d20 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
25d30 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
25d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
25d50 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
25d60 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
25d70 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
25d80 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
25d90 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
25da0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
25db0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
25dc0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
25dd0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
25de0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
25df0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
25e00 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
25e10 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
25e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
25e30 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
25e40 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
25e50 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
25e60 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
25e70 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
25e80 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
25e90 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
25ea0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
25eb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
25ec0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
25ed0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
25ee0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
25ef0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
25f00 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
25f10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
25f20 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
25f30 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
25f40 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
25f50 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
25f60 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
25f70 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
25f80 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
25f90 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
25fa0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
25fb0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25fc0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
25fd0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
25fe0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
25ff0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
26000 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
26010 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
26020 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
26030 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
26040 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26050 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26060 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
26070 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26080 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
26090 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
260a0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
260b0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
260c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
260d0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
260e0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
260f0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26100 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26110 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26120 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26130 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
26140 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26150 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
26160 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
26170 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
26180 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
26190 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
261a0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
261b0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
261c0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
261d0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
261e0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
261f0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26200 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26210 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26220 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26230 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
26240 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26250 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
26260 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
26270 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
26280 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
26290 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
262a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
262b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
262c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
262d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
262e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
262f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26300 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26310 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26320 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26330 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
26340 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
26350 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
26360 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
26370 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
26380 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
26390 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
263a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
263b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
263c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
263d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
263e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
263f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
26400 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
26410 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
26420 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26430 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
26440 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26450 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
26460 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
26470 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
26480 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
26490 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
264a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
264b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
264c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
264d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
264e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
264f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
26500 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
26510 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
26520 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
26530 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
26540 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
26550 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26560 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26570 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26580 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26590 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
265a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
265b0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
265c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
265d0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
265e0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
265f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26600 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
26610 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26620 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
26630 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26640 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
26650 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26660 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26670 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26680 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26690 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
266a0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
266b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
266c0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
266d0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
266e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
266f0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
26700 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
26710 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
26720 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
26730 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26740 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
26750 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
26760 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
26770 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
26780 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
26790 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
267a0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
267b0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
267c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
267d0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
267e0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
267f0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
26800 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
26810 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
26820 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
26830 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
26840 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
26850 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26860 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
26870 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
26880 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
26890 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
268a0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
268b0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
268c0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
268d0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
268e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
268f0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
26900 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
26910 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
26920 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
26930 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
26940 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
26950 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
26960 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
26970 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
26980 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
26990 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
269a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
269b0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
269c0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
269d0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
269e0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
269f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
26a00 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
26a10 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
26a20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
26a30 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
26a40 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
26a50 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
26a60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
26a70 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
26a80 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
26a90 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
26aa0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
26ab0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
26ac0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
26ad0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
26ae0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
26af0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
26b00 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
26b10 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
26b20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
26b30 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
26b40 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
26b50 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
26b60 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
26b70 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
26b80 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
26b90 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
26ba0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
26bb0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
26bc0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
26bd0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
26be0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
26bf0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
26c00 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
26c10 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
26c20 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
26c30 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
26c40 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
26c50 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
26c60 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
26c70 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
26c80 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
26c90 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
26ca0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
26cb0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
26cc0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
26cd0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
26ce0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
26cf0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
26d00 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
26d10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26d20 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
26d30 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
26d40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
26d50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
26d60 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26d70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
26d80 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
26d90 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
26da0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
26db0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
26dc0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
26dd0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
26de0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
26df0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
26e00 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
26e10 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
26e20 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26e30 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
26e40 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
26e50 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26e60 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
26e70 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
26e80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
26e90 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
26ea0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
26eb0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
26ec0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
26ed0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
26ee0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
26ef0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26f00 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
26f10 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
26f20 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
26f30 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
26f40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26f50 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
26f60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
26f70 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
26f80 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
26f90 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
26fa0 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
26fb0 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
26fc0 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
26fd0 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
26fe0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
26ff0 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
27000 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
27010 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
27020 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27030 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
27040 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
27050 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
27060 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27070 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
27080 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
27090 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
270a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
270b0 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
270c0 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
270d0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
270e0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
270f0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
27100 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
27110 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27120 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
27130 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
27140 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27150 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
27160 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
27170 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
27180 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
27190 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
271a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
271b0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
271c0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
271d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
271e0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
271f0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
27200 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
27210 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27220 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
27230 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27240 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
27250 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27260 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
27270 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
27280 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
27290 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
272a0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
272b0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
272c0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
272d0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
272e0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
272f0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27300 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27310 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27320 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
27330 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27340 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27350 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
27360 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
27370 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
27380 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
27390 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
273a0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
273b0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
273c0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
273d0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
273e0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
273f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27400 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
27410 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27420 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
27430 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
27440 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
27450 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
27460 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
27470 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27480 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
27490 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
274a0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
274b0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
274c0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
274d0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
274e0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
274f0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
27500 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
27510 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
27520 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
27530 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
27540 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
27550 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
27560 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
27570 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
27580 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
27590 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
275a0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
275b0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
275c0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
275d0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
275e0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
275f0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
27600 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
27610 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
27620 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
27630 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
27640 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
27650 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
27660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27670 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
27680 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27690 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
276a0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
276b0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
276c0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
276d0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
276e0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
276f0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
27700 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
27710 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
27720 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
27730 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
27740 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
27750 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
27760 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
27770 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
27780 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
27790 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
277a0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
277b0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
277c0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
277d0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
277e0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
277f0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
27800 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27810 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
27820 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
27830 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27840 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
27850 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27860 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
27870 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
27880 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
27890 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
278a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
278b0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
278c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
278d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
278e0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
278f0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
27900 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
27910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27920 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
27930 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
27940 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
27950 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
27960 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
27970 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
27980 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
27990 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
279a0 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
279b0 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
279c0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
279d0 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
279e0 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
279f0 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
27a00 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
27a10 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
27a20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a30 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
27a40 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
27a50 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
27a60 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
27a70 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
27a80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a90 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
27aa0 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
27ab0 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
27ac0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27ad0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
27ae0 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
27af0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
27b00 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
27b10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27b20 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
27b30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27b40 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
27b50 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
27b60 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
27b70 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
27b80 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
27b90 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
27ba0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
27bb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
27bc0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
27bd0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
27be0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
27bf0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27c00 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
27c10 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
27c20 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
27c30 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
27c40 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
27c50 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
27c60 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
27c70 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
27c80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
27c90 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
27ca0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
27cb0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
27cc0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
27cd0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
27ce0 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
27cf0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
27d00 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
27d10 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
27d20 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
27d30 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
27d40 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
27d50 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
27d60 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
27d70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
27d80 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
27d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27da0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
27db0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
27dc0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
27dd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
27de0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
27df0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
27e00 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
27e10 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
27e20 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
27e30 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
27e40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
27e50 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
27e60 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
27e70 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
27e80 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
27e90 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
27ea0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
27eb0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
27ec0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
27ed0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
27ee0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
27ef0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
27f00 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
27f10 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
27f20 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
27f30 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
27f40 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
27f50 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
27f60 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
27f70 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
27f80 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
27f90 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
27fa0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
27fb0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
27fc0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
27fd0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
27fe0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
27ff0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
28000 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
28010 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
28020 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
28030 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
28040 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
28050 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
28060 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
28070 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
28080 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28090 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
280a0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
280b0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
280c0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
280d0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
280e0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
280f0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
28100 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
28110 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
28120 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
28130 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
28140 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
28150 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
28160 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
28170 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
28180 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
28190 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
281a0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
281b0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
281c0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
281d0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
281e0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
281f0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
28200 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
28210 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
28220 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
28230 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
28240 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
28250 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
28260 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
28270 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
28280 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
28290 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
282a0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
282b0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
282c0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
282d0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
282e0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
282f0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
28300 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28310 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
28320 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
28330 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
28340 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
28350 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
28360 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
28370 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
28380 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
28390 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
283a0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
283b0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
283c0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
283d0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
283e0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
283f0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
28400 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
28410 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
28420 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
28430 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
28440 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
28450 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
28460 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
28470 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
28480 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
28490 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
284a0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
284b0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
284c0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
284d0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
284e0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
284f0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
28500 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
28510 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
28520 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
28530 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
28540 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
28550 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
28560 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
28570 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
28580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
28590 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
285a0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
285b0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
285c0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
285d0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
285e0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
285f0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
28600 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
28610 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
28620 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
28630 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28640 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
28650 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
28660 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28670 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
28680 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
28690 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
286a0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
286b0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
286c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
286d0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
286e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
286f0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
28700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
28710 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
28720 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
28730 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
28740 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28750 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
28760 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28770 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
28780 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28790 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
287a0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
287b0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
287c0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
287d0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
287e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
287f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
28800 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
28810 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
28820 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
28830 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28840 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
28850 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
28860 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
28870 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
28880 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
28890 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
288a0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
288b0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
288c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
288d0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
288e0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
288f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
28900 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
28910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28920 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
28930 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
28940 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
28950 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
28960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
28970 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
28980 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
28990 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
289a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
289b0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
289c0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
289d0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
289e0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
289f0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
28a00 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
28a10 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
28a20 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
28a30 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
28a40 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
28a50 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
28a60 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
28a70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
28a90 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
28aa0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
28ab0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
28ac0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28ad0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
28ae0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
28af0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
28b00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28b10 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
28b20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28b30 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
28b40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28b50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
28b60 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
28b70 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
28b80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
28b90 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
28ba0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
28bb0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28bc0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
28bd0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
28be0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
28bf0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
28c00 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
28c10 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
28c20 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
28c30 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
28c40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28c50 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
28c60 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
28c70 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28c80 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
28c90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28ca0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
28cb0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
28cc0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
28cd0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
28ce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
28cf0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
28d00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
28d10 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
28d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28d30 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
28d40 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
28d50 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
28d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28d70 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
28d80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
28d90 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
28da0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
28db0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
28dc0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
28dd0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
28de0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
28df0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28e00 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
28e10 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
28e20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
28e30 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
28e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28e50 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
28e60 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
28e70 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
28e80 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
28e90 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
28ea0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
28eb0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
28ec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
28ed0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
28ee0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
28ef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
28f00 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
28f10 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
28f20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
28f30 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
28f40 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
28f50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
28f60 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
28f70 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
28f80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28f90 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
28fa0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
28fb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28fc0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
28fd0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
28fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28ff0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29000 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29020 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29030 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29050 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29060 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
29070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29080 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
29090 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
290a0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
290b0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
290c0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
290d0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
290e0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
290f0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
29100 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
29110 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
29120 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
29130 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
29140 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
29150 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29160 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
29170 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
29180 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
29190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
291a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
291b0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
291c0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
291d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
291e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
291f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
29200 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
29210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29220 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
29230 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
29240 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
29250 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
29260 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
29270 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
29280 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
29290 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
292a0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
292b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
292c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
292d0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
292e0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
292f0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
29300 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
29310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29320 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
29330 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
29340 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
29350 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29360 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
29370 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
29380 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29390 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
293a0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
293b0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
293c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
293d0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
293e0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
293f0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
29400 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
29410 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
29420 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
29430 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
29440 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
29450 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
29460 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
29470 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
29480 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
29490 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
294a0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
294b0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
294c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
294d0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
294e0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
294f0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
29500 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
29510 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
29520 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
29530 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
29540 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
29550 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
29560 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
29570 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
29580 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
29590 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
295a0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
295b0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
295c0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
295d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
295e0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
295f0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
29600 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
29610 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
29620 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
29630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29640 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
29650 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
29660 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
29670 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
29680 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
29690 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
296a0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
296b0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
296c0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
296d0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
296e0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
296f0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
29700 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
29710 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
29720 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
29730 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
29740 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
29750 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
29760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
29770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29780 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
29790 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
297a0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
297b0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
297c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
297d0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
297e0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
297f0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
29800 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
29810 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
29820 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
29830 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
29840 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
29850 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
29860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29870 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
29880 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
29890 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
298a0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
298b0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
298c0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
298d0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
298e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
298f0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
29900 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
29910 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
29920 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
29930 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29940 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
29950 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
29960 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
29970 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
29980 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
29990 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
299a0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
299b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
299c0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
299d0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
299e0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
299f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
29a00 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
29a10 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
29a20 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
29a30 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
29a40 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
29a50 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
29a60 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
29a70 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
29a80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29a90 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
29aa0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
29ab0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
29ac0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
29ad0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
29ae0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
29af0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
29b00 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
29b10 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
29b20 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
29b30 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
29b40 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
29b50 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
29b60 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
29b70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
29b80 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
29b90 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
29ba0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
29bb0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
29bc0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
29bd0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
29be0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29bf0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
29c00 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
29c10 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
29c20 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
29c30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29c40 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
29c50 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
29c60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
29c70 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
29c80 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
29c90 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
29ca0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
29cb0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
29cc0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
29cd0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
29ce0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
29cf0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
29d00 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
29d10 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
29d20 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
29d30 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
29d40 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
29d50 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
29d60 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
29d70 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
29d80 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
29d90 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
29da0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
29db0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
29dc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
29dd0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
29de0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
29df0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
29e00 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
29e10 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
29e20 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
29e30 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
29e40 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
29e50 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
29e60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
29e70 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
29e80 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
29e90 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
29ea0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
29eb0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
29ec0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
29ed0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
29ee0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
29ef0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
29f00 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
29f10 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
29f20 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
29f30 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
29f40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
29f50 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
29f60 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
29f70 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
29f80 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
29f90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
29fa0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
29fb0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
29fc0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
29fd0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
29fe0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
29ff0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a000 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a010 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2a020 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a030 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2a040 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a050 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a060 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a070 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a080 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a090 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a0a0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a0b0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a0c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2a0d0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a0e0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2a0f0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2a100 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2a110 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a120 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a140 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a150 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a160 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a170 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a180 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a190 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a1a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a1b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a1c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a1d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a1e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a1f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a200 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a210 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a220 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a230 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a240 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2a250 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2a260 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2a270 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a280 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a290 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2a2a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2a2b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a2c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2a2d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a2f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a300 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a310 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a320 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a330 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a340 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a350 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2a360 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a370 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a380 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a390 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2a3a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2a3b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a3c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a3d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a3e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2a3f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a400 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2a410 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2a420 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a430 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a440 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a450 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a460 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a470 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a480 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a490 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a4a0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a4b0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a4c0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a4d0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2a4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a4f0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2a500 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2a510 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2a520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a530 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2a540 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a550 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2a560 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2a570 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2a580 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2a590 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2a5a0 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2a5b0 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2a5c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a5d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a5e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2a5f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a600 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2a610 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a620 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a630 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2a640 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2a650 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2a660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a670 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2a680 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2a690 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2a6a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2a6b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a6c0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2a6d0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2a6e0 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2a6f0 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2a700 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2a710 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2a720 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2a730 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2a740 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2a750 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2a760 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2a770 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2a780 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2a790 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2a7a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2a7b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2a7c0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2a7d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2a7e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2a7f0 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2a800 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2a810 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2a820 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2a830 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2a840 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2a850 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2a860 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2a870 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2a880 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2a890 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2a8a0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2a8b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2a8c0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2a8d0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2a8e0 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2a8f0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2a900 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2a910 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2a920 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2a930 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2a940 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2a950 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2a960 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2a970 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2a980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2a990 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2a9a0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2a9b0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2a9c0 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2a9d0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2a9e0 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2a9f0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2aa00 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2aa10 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2aa20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2aa30 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2aa40 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2aa50 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2aa60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2aa70 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2aa80 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2aa90 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2aaa0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2aab0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2aac0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2aad0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2aae0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2aaf0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2ab00 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2ab10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2ab20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ab30 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2ab40 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2ab50 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2ab60 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2ab70 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ab80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ab90 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2aba0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2abb0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2abc0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2abd0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2abe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2abf0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2ac00 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2ac10 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2ac20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2ac30 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2ac40 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2ac50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2ac60 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2ac70 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2ac80 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2ac90 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2aca0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2acb0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2acc0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2acd0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2ace0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2acf0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2ad00 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2ad10 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2ad20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2ad30 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2ad40 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2ad50 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2ad60 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2ad70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2ad80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2ad90 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2ada0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2adb0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2adc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2add0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2ade0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2adf0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2ae00 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2ae10 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2ae20 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2ae30 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2ae40 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2ae50 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2ae60 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2ae70 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2ae80 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2ae90 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2aea0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2aeb0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2aec0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2aed0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2aee0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2aef0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2af00 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2af10 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2af20 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2af30 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2af40 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2af50 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2af60 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2af70 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2af80 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2af90 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2afa0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2afb0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2afc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2afd0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2afe0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2aff0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2b000 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2b010 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2b020 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2b030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2b040 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2b050 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2b060 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2b070 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2b080 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
2b090 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b0a0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2b0b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b0c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b0d0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2b0e0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2b0f0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2b100 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b110 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b120 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2b130 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2b140 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2b150 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2b160 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2b170 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2b180 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2b190 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2b1a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2b1b0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2b1c0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2b1d0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2b1e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2b1f0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2b200 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2b210 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2b220 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b230 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2b240 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2b250 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2b260 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2b270 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2b280 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2b290 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2b2a0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2b2b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2b2c0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2b2d0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2b2e0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2b2f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2b300 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2b310 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2b320 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2b330 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2b340 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2b350 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2b360 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2b370 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2b380 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2b390 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2b3a0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2b3b0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2b3c0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2b3d0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2b3e0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2b3f0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2b400 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2b410 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2b420 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2b430 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2b440 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2b450 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2b460 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2b470 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b490 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2b4a0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2b4b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2b4c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b4d0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2b4e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b4f0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2b500 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2b510 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2b520 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2b530 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2b540 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2b550 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2b560 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2b570 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2b580 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2b590 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2b5a0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2b5b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b5c0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2b5d0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2b5e0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2b5f0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2b600 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2b610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b620 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2b630 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2b640 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2b650 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2b660 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2b670 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b680 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2b690 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2b6a0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2b6b0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2b6c0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2b6d0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2b6e0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2b6f0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2b700 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2b710 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2b720 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2b730 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2b740 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b750 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2b760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2b770 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2b780 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2b790 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2b7a0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2b7b0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2b7c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2b7d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2b7e0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2b7f0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2b800 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2b810 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2b820 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2b830 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2b840 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2b850 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2b860 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2b870 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2b880 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2b890 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2b8a0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2b8b0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2b8c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2b8d0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2b8e0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2b8f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2b900 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2b910 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2b920 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2b930 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2b940 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2b950 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2b960 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2b970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2b980 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2b990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2b9a0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2b9b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2b9c0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2b9d0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2b9e0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2b9f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ba00 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2ba10 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2ba20 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2ba30 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2ba40 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2ba50 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2ba60 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2ba70 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2ba80 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2ba90 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2baa0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2bab0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2bac0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2bad0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2bae0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2baf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2bb00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bb10 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2bb20 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2bb30 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2bb40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2bb50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2bb60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2bb70 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2bb80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2bb90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2bba0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2bbb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2bbc0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2bbd0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2bbe0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bbf0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2bc00 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2bc10 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2bc20 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2bc30 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2bc40 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2bc50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2bc60 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2bc70 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2bc80 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2bc90 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2bca0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bcb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2bcc0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2bcd0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
2bce0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2bcf0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2bd00 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2bd10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2bd20 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2bd30 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2bd40 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2bd50 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2bd60 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2bd70 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2bd80 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2bd90 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2bda0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2bdb0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2bdc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bdd0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2bde0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2bdf0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2be00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2be10 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2be20 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2be30 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2be40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2be50 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2be60 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2be70 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2be80 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2be90 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2bea0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2beb0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2bec0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2bed0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2bee0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2bef0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2bf00 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2bf10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2bf20 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2bf30 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2bf40 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2bf50 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2bf60 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2bf70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2bf80 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2bf90 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2bfa0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2bfb0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2bfc0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2bfd0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2bfe0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2bff0 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2c000 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c010 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2c020 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2c030 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2c040 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c050 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2c060 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2c070 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2c080 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2c090 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2c0a0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2c0b0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2c0c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2c0d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2c0e0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2c0f0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2c100 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2c110 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2c120 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2c130 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2c140 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2c150 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2c160 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2c170 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2c180 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2c190 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2c1a0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2c1b0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2c1c0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2c1d0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2c1e0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2c1f0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2c200 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2c210 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2c220 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2c230 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2c240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2c250 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2c260 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2c270 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2c280 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2c290 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2c2a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c2b0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2c2c0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2c2d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2c2e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2c2f0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2c300 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2c310 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2c320 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2c330 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2c340 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2c350 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2c360 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2c370 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2c380 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2c390 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2c3a0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2c3b0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2c3c0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2c3d0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2c3e0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2c3f0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2c400 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2c410 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2c420 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c430 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2c440 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2c450 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2c460 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2c470 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2c480 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2c490 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2c4a0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2c4b0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2c4c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2c4d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2c4e0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2c4f0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2c500 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2c510 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2c520 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2c530 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2c540 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2c550 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2c560 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2c570 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2c580 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2c590 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2c5a0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2c5b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2c5c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2c5d0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2c5e0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2c5f0 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2c600 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2c610 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2c620 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2c630 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2c640 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2c650 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2c660 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2c670 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2c680 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2c690 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2c6a0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2c6b0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2c6c0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2c6d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2c6e0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2c6f0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2c700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c710 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2c720 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2c730 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2c740 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2c750 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2c760 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2c770 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2c780 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2c790 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2c7a0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2c7b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2c7c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2c7d0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2c7e0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2c7f0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2c800 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2c810 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2c820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2c830 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2c840 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2c850 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2c860 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2c870 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2c880 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2c890 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2c8a0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2c8b0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2c8c0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2c8d0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2c8e0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2c8f0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2c900 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2c910 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2c920 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2c930 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2c940 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2c950 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c960 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2c970 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2c980 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2c990 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2c9a0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2c9b0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2c9c0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2c9d0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2c9e0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2c9f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2ca00 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2ca10 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2ca20 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2ca30 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2ca40 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2ca50 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2ca60 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2ca70 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2ca80 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2ca90 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2caa0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2cab0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2cac0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2cad0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2cae0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2caf0 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2cb00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2cb10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2cb20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2cb30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2cb40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2cb50 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2cb60 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2cb70 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2cb80 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2cb90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2cba0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2cbb0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2cbc0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2cbd0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2cbe0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2cbf0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2cc00 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2cc10 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2cc20 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2cc30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2cc40 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2cc50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2cc60 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2cc70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cc80 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2cc90 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2cca0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2ccb0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2ccc0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2ccd0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2cce0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2ccf0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2cd00 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2cd10 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2cd20 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2cd30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2cd40 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2cd50 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2cd60 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2cd70 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2cd80 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2cd90 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2cda0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2cdb0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2cdc0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2cdd0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2cde0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2cdf0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2ce00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ce10 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2ce20 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2ce30 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2ce40 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2ce50 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2ce60 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2ce70 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2ce80 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2ce90 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2cea0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2ceb0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2cec0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2ced0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2cee0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2cef0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2cf00 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2cf10 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2cf20 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2cf30 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2cf40 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2cf50 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2cf60 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2cf70 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2cf80 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2cf90 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2cfa0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2cfb0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2cfc0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2cfd0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2cfe0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2cff0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2d000 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2d010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d020 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2d030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2d040 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2d050 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d060 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2d070 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2d080 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d090 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2d0a0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2d0b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2d0c0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2d0d0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2d0e0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2d0f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d100 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2d110 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2d120 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2d130 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2d140 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2d150 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2d160 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2d170 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2d180 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2d190 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2d1a0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2d1b0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2d1c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d1d0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2d1e0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2d1f0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2d200 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2d210 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2d220 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2d230 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2d240 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2d250 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2d260 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2d270 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2d280 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2d290 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2d2a0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2d2b0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2d2c0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2d2d0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2d2e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2d2f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2d300 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2d310 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2d320 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2d330 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2d340 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2d350 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2d360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d370 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2d380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d390 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2d3a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2d3b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d3c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2d3d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2d3e0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2d3f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2d400 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2d410 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2d420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d430 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2d440 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2d450 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2d460 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2d470 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2d480 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2d490 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2d4a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2d4b0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2d4c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2d4d0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2d4e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2d4f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d500 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2d510 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2d520 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
2d530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2d540 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2d550 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2d560 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2d570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2d580 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2d590 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d5b0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2d5c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d5d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2d5e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d5f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d600 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2d610 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d620 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2d630 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2d640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d650 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2d660 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2d670 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2d680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2d690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d6a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2d6b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2d6c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2d6d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2d6e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2d6f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2d700 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2d710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d720 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2d730 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2d740 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2d750 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2d760 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d770 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2d780 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2d790 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2d7a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2d7b0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2d7c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2d7d0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2d7e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2d7f0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2d800 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2d810 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2d820 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2d830 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2d840 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2d850 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2d860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d870 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2d880 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2d890 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2d8a0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2d8b0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2d8c0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2d8d0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2d8e0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2d8f0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2d900 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2d910 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2d920 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2d930 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2d940 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2d950 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2d960 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2d970 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2d980 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2d990 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2d9a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2d9b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d9c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2d9d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2d9e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2d9f0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2da00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2da10 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2da20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2da30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2da40 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2da50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2da60 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2da70 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2da80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2da90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2daa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2dab0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2dac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dad0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2dae0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2daf0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2db00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2db10 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2db20 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2db30 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2db40 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2db50 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2db60 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2db70 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2db80 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2db90 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2dba0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2dbb0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2dbc0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2dbd0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2dbe0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2dbf0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2dc00 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2dc10 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2dc20 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2dc30 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2dc40 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2dc50 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2dc60 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2dc70 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2dc80 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2dc90 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2dca0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2dcb0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2dcc0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2dcd0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2dce0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2dcf0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2dd00 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2dd10 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2dd20 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2dd30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2dd40 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2dd50 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2dd60 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2dd70 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2dd80 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2dd90 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2dda0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2ddb0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2ddc0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2ddd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2dde0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2ddf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2de00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2de10 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2de20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2de30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2de40 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2de50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2de60 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2de70 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2de80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2de90 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2dea0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2deb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dec0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2ded0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2dee0 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
2def0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2df00 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2df10 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2df20 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2df30 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2df40 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2df50 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2df60 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2df70 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2df80 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2df90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2dfa0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2dfb0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2dfc0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2dfd0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2dfe0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2dff0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2e000 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2e010 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2e020 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2e030 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2e040 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2e050 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2e060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e070 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2e080 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e090 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2e0a0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2e0b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e0c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2e0d0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2e0e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e0f0 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
2e100 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2e110 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2e120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2e130 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2e140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e150 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2e160 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2e170 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2e180 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e190 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2e1a0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2e1b0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2e1c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e1d0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2e1e0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2e1f0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2e200 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2e210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e220 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2e230 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2e240 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2e250 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2e260 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2e270 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2e280 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e290 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2e2a0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2e2b0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2e2c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e2d0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2e2e0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2e2f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2e300 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2e310 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2e320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e330 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2e340 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2e350 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2e360 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2e370 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2e380 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2e390 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2e3a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e3b0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2e3c0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2e3d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2e3e0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2e3f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e400 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2e410 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2e420 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2e430 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2e450 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2e460 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2e470 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2e480 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2e490 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2e4a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e4b0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2e4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2e4d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2e4e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e4f0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2e500 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2e510 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2e520 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2e530 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e540 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2e550 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2e560 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2e570 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e580 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2e590 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2e5a0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2e5b0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2e5c0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2e5d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2e5e0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2e5f0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2e600 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2e610 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2e620 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2e630 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2e640 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2e650 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2e660 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2e670 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2e680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e690 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2e6a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2e6b0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2e6c0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2e6d0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2e6e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2e6f0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2e700 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2e710 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2e720 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e730 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2e740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e750 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2e760 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2e770 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2e780 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2e790 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2e7a0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2e7b0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2e7c0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2e7d0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2e7e0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2e7f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2e800 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2e810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2e820 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2e830 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2e840 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2e850 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2e860 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2e870 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2e880 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2e890 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2e8a0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2e8b0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2e8c0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2e8d0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2e8e0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2e8f0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2e900 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2e910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e920 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2e930 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2e940 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e950 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2e960 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e970 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2e980 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2e990 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2e9a0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2e9b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e9c0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2e9d0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2e9e0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2e9f0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2ea00 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2ea10 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2ea20 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2ea30 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2ea40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2ea50 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2ea60 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2ea70 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2ea80 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2ea90 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2eaa0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2eab0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2eac0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2ead0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2eae0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2eaf0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2eb00 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2eb10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2eb20 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2eb30 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2eb40 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2eb50 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2eb60 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2eb70 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2eb80 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2eb90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eba0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2ebb0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2ebc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ebd0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2ebe0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2ebf0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2ec00 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2ec10 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2ec20 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2ec30 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2ec40 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2ec50 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2ec60 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2ec70 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2ec80 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2ec90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2eca0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2ecb0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2ecc0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2ecd0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2ece0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2ecf0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2ed00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2ed10 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2ed20 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2ed30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2ed40 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2ed50 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2ed60 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2ed70 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2ed80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2ed90 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2eda0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2edb0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2edc0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2edd0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2ede0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2edf0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2ee00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2ee10 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2ee20 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2ee30 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2ee40 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2ee50 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2ee60 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2ee70 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2ee80 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2ee90 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2eea0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2eeb0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2eec0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2eed0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2eee0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2eef0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2ef00 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2ef10 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2ef20 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2ef30 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2ef40 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2ef50 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2ef60 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2ef70 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2ef80 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2ef90 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2efa0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2efb0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2efc0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2efd0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2efe0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2eff0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2f000 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2f010 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2f020 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2f030 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2f040 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2f050 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2f060 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2f070 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2f080 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2f090 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2f0a0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2f0b0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2f0c0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2f0d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2f0e0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2f0f0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2f100 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2f110 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2f120 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2f130 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2f140 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2f150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2f160 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2f170 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2f180 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2f190 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2f1a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2f1b0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2f1c0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2f1d0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2f1e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f1f0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2f200 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f210 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2f220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f230 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2f240 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f250 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2f260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2f270 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2f280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f290 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2f2a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2f2b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f2c0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2f2d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2f2e0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2f2f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f300 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2f310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f320 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2f330 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f340 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2f350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f370 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2f380 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2f390 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2f3a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f3b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2f3c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2f3d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f3e0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2f3f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2f400 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2f410 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2f420 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2f430 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2f440 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2f450 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2f460 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2f470 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2f480 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2f490 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2f4a0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2f4b0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2f4c0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2f4d0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2f4e0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2f4f0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2f500 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2f510 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2f520 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2f530 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2f540 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2f550 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2f560 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2f570 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2f580 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2f590 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2f5a0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2f5b0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2f5c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2f5d0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2f5e0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2f5f0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2f600 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2f610 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2f620 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2f630 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2f640 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2f650 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2f660 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2f670 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2f680 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2f690 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2f6a0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2f6b0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2f6c0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2f6d0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2f6e0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2f6f0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2f700 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2f710 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2f720 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2f730 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2f740 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2f750 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2f760 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2f770 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2f780 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2f790 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2f7a0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2f7b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2f7c0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2f7d0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2f7e0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2f7f0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2f800 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2f810 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f820 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2f830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f840 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2f860 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2f870 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2f880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2f890 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2f8a0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2f8b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f8c0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2f8d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f8e0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2f8f0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2f900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f910 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2f920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2f930 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2f940 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2f950 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2f960 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2f970 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f980 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2f990 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2f9a0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2f9b0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2f9c0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2f9d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2f9e0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2f9f0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2fa00 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2fa10 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2fa20 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2fa30 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2fa40 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2fa50 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2fa60 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2fa70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2fa80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2fa90 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2faa0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2fab0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2fac0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2fad0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2fae0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2faf0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2fb00 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2fb10 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2fb20 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2fb30 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2fb40 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2fb50 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2fb60 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2fb70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2fb80 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2fb90 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2fba0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2fbb0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2fbc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2fbd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2fbe0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2fbf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2fc00 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2fc10 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2fc20 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2fc30 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2fc40 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2fc50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2fc60 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2fc70 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2fc80 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2fc90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2fca0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2fcb0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2fcc0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2fcd0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2fce0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2fcf0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2fd00 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2fd10 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2fd20 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2fd30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2fd40 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2fd50 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2fd60 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2fd70 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2fd80 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2fd90 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2fda0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2fdb0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2fdc0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2fdd0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2fde0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2fdf0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2fe00 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2fe10 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2fe20 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2fe30 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2fe40 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2fe50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2fe60 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2fe70 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2fe80 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2fe90 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2fea0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2feb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2fec0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2fed0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2fee0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2fef0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2ff00 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2ff10 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2ff20 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2ff30 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2ff40 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2ff50 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2ff60 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2ff70 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2ff80 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2ff90 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2ffa0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2ffb0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2ffc0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2ffd0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2ffe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2fff0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
30000 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
30010 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
30020 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
30030 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
30040 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
30050 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
30060 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
30070 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
30080 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
30090 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
300a0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
300b0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
300c0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
300d0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
300e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
300f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
30100 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
30110 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
30120 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
30130 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
30140 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
30150 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
30160 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
30170 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
30180 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
30190 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
301a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
301b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
301c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
301d0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
301e0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
301f0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
30200 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30210 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
30220 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
30230 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
30240 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
30250 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
30260 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
30270 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
30280 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
30290 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
302a0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
302b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
302c0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
302d0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
302e0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
302f0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
30300 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
30310 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
30320 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
30330 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
30340 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
30350 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
30360 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30380 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
30390 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
303a0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
303b0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
303c0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
303d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
303e0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
303f0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
30400 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
30410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30420 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
30430 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
30440 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
30450 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
30460 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
30470 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
30480 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
30490 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
304a0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
304b0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
304c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
304d0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
304e0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
304f0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
30500 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
30510 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
30520 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
30530 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
30540 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
30550 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
30560 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
30570 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
30580 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
30590 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
305a0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
305b0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
305c0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
305d0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
305e0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
305f0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
30600 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
30610 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
30620 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
30630 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
30640 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
30650 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
30660 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
30670 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
30680 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
30690 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
306a0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
306b0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
306c0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
306d0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
306e0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
306f0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
30700 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
30710 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
30720 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
30730 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
30740 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
30750 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
30760 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
30770 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
30780 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
30790 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
307a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
307b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
307c0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
307d0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
307e0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
307f0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
30800 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
30810 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
30820 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
30830 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
30840 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
30850 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
30860 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
30870 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
30880 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
30890 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
308a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
308b0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
308c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
308d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
308e0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
308f0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
30900 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
30910 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
30920 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30930 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
30940 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
30950 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
30960 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
30970 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
30980 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
30990 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
309a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
309b0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
309c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
309d0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
309e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
309f0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
30a00 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
30a10 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
30a20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30a40 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30a50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30a60 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
30a70 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
30a80 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
30a90 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
30aa0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
30ab0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
30ac0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
30ad0 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
30ae0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
30af0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
30b00 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
30b10 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
30b20 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
30b30 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
30b40 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
30b50 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
30b60 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
30b70 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
30b80 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30b90 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
30ba0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
30bb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30bc0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
30bd0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
30be0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30bf0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
30c00 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
30c10 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
30c20 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30c30 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
30c40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30c50 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
30c60 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
30c70 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
30c80 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
30c90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
30ca0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
30cb0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
30cc0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
30cd0 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
30ce0 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
30cf0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
30d00 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
30d10 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
30d20 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
30d30 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
30d40 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
30d50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30d60 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
30d70 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
30d80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
30d90 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
30da0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30db0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
30dc0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
30dd0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
30de0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
30df0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
30e00 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
30e10 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
30e20 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
30e30 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
30e40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
30e50 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
30e60 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
30e70 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
30e80 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
30e90 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
30ea0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
30eb0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
30ec0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
30ed0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
30ee0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
30ef0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
30f00 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
30f10 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
30f20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
30f30 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
30f40 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
30f50 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
30f60 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
30f70 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
30f80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
30f90 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
30fa0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
30fb0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
30fc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
30fd0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
30fe0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
30ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
31000 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
31010 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
31020 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
31030 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
31040 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31050 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
31060 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
31070 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
31080 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
31090 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
310a0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
310b0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
310c0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
310d0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
310e0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
310f0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
31100 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
31120 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
31130 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
31140 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
31150 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
31160 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
31170 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
31180 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
31190 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
311a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
311b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
311c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
311d0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
311e0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
311f0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
31200 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
31210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31220 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
31230 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
31240 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
31250 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
31260 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
31270 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
31280 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
31290 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
312a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
312b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
312c0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
312d0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
312e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
312f0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
31300 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
31310 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
31320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31330 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
31340 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31350 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
31360 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
31370 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
31380 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
31390 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
313a0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
313b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
313c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
313d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
313e0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
313f0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
31400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
31410 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
31420 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
31430 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
31440 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
31450 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31460 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
31470 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
31480 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
31490 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
314a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
314b0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
314c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
314d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
314e0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
314f0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
31500 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
31510 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
31520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
31530 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
31540 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
31550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31560 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
31570 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
31580 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
31590 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
315a0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
315b0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
315c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
315d0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
315e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
315f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31600 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31610 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
31620 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31630 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
31640 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
31650 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
31660 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
31670 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
31680 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
31690 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
316a0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
316b0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
316c0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
316d0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
316e0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
316f0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
31700 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
31710 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31720 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
31730 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
31740 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
31750 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
31760 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
31770 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
31780 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
31790 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
317a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
317b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
317c0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
317d0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
317e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
317f0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
31800 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
31810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31820 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
31830 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
31840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
31850 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
31860 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
31870 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
31880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31890 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
318a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
318b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
318c0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
318d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
318e0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
318f0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
31900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31910 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
31920 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
31930 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
31940 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
31950 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
31960 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31970 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
31980 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31990 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
319a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
319b0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
319c0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
319d0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
319e0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
319f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31a00 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
31a10 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31a20 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
31a30 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31a40 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
31a50 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
31a60 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31a70 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
31a80 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
31a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31aa0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
31ab0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
31ac0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31ad0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
31ae0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
31af0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31b00 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
31b10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31b20 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
31b30 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
31b40 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
31b50 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
31b60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31b70 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
31b80 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
31b90 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
31ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31bb0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
31bc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
31bd0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
31be0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
31bf0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
31c00 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
31c10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31c20 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
31c30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31c40 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
31c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31c60 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
31c70 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
31c80 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
31c90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
31ca0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
31cb0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
31cc0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
31cd0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
31ce0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
31cf0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
31d00 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
31d10 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
31d20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
31d30 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
31d40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31d50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31d60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31d70 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
31d80 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
31d90 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
31da0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
31db0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
31dc0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
31dd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31de0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
31df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31e00 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
31e10 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
31e20 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
31e30 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
31e40 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
31e50 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
31e60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
31e70 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
31e80 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
31e90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
31ea0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
31eb0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
31ec0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
31ed0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
31ee0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
31ef0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31f00 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
31f10 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
31f20 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
31f30 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
31f40 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
31f50 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
31f60 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
31f70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
31f80 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
31f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
31fa0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
31fb0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
31fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31fd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
31fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
31ff0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
32000 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
32010 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
32020 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
32030 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
32040 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
32050 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32060 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
32070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32080 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
32090 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
320a0 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
320b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
320c0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
320d0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
320e0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
320f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
32100 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
32110 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
32120 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
32130 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
32140 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
32150 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
32160 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
32170 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
32180 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
32190 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
321a0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
321b0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
321c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
321d0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
321e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
321f0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
32200 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
32210 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
32220 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
32230 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
32240 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
32250 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
32260 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
32270 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
32280 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
32290 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
322a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
322b0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
322c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
322d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
322e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
322f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32300 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
32310 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
32320 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
32330 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32340 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
32350 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
32360 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
32370 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
32380 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
32390 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
323a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
323b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
323c0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
323d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
323e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
323f0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
32400 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
32410 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
32420 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
32430 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
32440 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
32450 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
32460 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
32470 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
32480 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
32490 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
324a0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
324b0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
324c0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
324d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
324e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
324f0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
32500 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
32510 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
32520 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
32530 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
32540 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32550 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32560 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
32570 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
32580 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
32590 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
325a0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
325b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
325c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
325d0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
325e0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
325f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
32600 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
32610 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
32620 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
32630 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
32640 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
32650 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
32660 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
32670 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
32680 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
32690 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
326a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
326b0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
326c0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
326d0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
326e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
326f0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
32700 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
32710 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
32720 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
32730 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
32740 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
32750 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
32760 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
32770 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
32780 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
32790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
327a0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
327b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
327c0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
327d0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
327e0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
327f0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
32800 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
32810 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
32820 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32830 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
32840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32850 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
32860 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
32870 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32880 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
32890 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
328a0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
328b0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
328c0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
328d0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
328e0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
328f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32900 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
32910 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
32920 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
32930 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
32940 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
32950 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
32960 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
32970 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
32980 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
32990 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
329a0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
329b0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
329c0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
329d0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
329e0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
329f0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
32a00 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
32a10 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
32a20 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
32a30 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
32a40 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
32a50 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
32a60 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
32a70 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
32a80 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
32a90 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
32aa0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
32ab0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
32ac0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
32ad0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
32ae0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
32af0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
32b00 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
32b10 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
32b20 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
32b30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
32b40 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
32b50 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
32b60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
32b70 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
32b80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32b90 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
32ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32bb0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
32bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32bd0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
32be0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
32bf0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
32c00 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
32c10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32c20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
32c30 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
32c40 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
32c50 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
32c60 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
32c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32c80 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
32c90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32ca0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
32cb0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
32cc0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
32cd0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
32ce0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
32cf0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32d10 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
32d20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
32d30 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
32d40 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
32d50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32d60 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
32d70 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
32d80 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
32d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32da0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
32db0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
32dc0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32dd0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
32de0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
32df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32e00 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
32e10 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
32e20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
32e30 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
32e40 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
32e50 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
32e60 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
32e70 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
32e80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32e90 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
32ea0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
32eb0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
32ec0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
32ed0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
32ee0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
32ef0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
32f00 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
32f10 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
32f20 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
32f30 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
32f40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
32f50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32f60 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
32f70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
32f80 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
32f90 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
32fa0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
32fb0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
32fc0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
32fd0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
32fe0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
32ff0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
33000 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
33010 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
33020 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
33030 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
33040 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
33050 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
33060 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
33070 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
33080 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
33090 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
330a0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
330b0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
330c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
330d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
330e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
330f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
33100 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
33110 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33120 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
33130 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
33140 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33150 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
33160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33170 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
33180 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
33190 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
331a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
331b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
331c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
331d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
331e0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
331f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
33200 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
33210 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33220 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
33230 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
33240 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33260 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33270 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
33280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
33290 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
332a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
332b0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
332c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
332d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
332e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
332f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
33300 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
33310 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
33320 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
33330 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33340 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
33350 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
33360 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
33370 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
33380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33390 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
333a0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
333b0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
333c0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
333d0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
333e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
333f0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
33400 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
33410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
33420 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
33430 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
33440 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
33450 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
33460 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
33470 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
33480 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
33490 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
334a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
334b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
334c0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
334d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
334e0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
334f0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
33500 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
33510 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
33520 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
33530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
33540 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
33550 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
33560 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
33570 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
33580 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
33590 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
335a0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
335b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
335c0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
335d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
335e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
335f0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
33600 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
33610 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
33620 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
33630 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33640 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33650 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
33660 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
33670 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
33680 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33690 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
336a0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
336b0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
336c0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
336d0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
336e0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
336f0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
33700 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
33710 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
33720 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
33730 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
33740 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
33750 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33760 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
33770 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
33780 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
33790 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
337a0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
337b0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
337c0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
337d0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
337e0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
337f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33800 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
33810 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
33820 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
33830 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33840 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33850 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
33860 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
33870 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
33880 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
33890 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
338a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
338b0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
338c0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
338d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
338e0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
338f0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
33900 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
33910 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
33920 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
33930 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
33940 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
33950 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
33960 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
33970 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
33980 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
33990 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
339a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
339b0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
339c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
339d0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
339e0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
339f0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
33a00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
33a10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
33a20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
33a30 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
33a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33a50 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
33a60 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
33a70 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
33a80 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
33a90 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
33aa0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
33ab0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
33ac0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
33ad0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
33ae0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
33af0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
33b00 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
33b10 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
33b20 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
33b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
33b40 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
33b50 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
33b60 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
33b70 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
33b80 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33b90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
33ba0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
33bb0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
33bc0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
33bd0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
33be0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33bf0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
33c00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33c10 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
33c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
33c30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
33c40 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
33c50 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
33c60 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
33c70 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
33c80 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
33c90 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
33ca0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
33cb0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
33cc0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
33cd0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
33ce0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
33cf0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
33d00 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
33d10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
33d20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
33d30 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
33d40 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
33d50 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
33d60 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
33d70 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
33d80 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
33d90 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
33da0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
33db0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
33dc0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
33dd0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
33de0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
33df0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
33e00 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
33e10 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
33e20 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
33e30 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
33e40 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
33e50 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
33e60 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
33e70 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
33e80 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
33e90 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
33ea0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
33eb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
33ec0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
33ed0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
33ee0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
33ef0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33f00 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
33f10 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
33f20 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
33f30 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
33f40 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
33f50 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
33f60 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
33f70 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
33f80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
33f90 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
33fa0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
33fb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33fc0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
33fd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
33fe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
33ff0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
34000 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
34010 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
34020 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
34030 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
34040 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
34050 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
34060 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34070 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34080 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34090 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
340a0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
340b0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
340c0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
340d0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
340e0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
340f0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
34100 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
34110 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
34120 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
34130 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
34140 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
34150 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
34160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
34170 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
34180 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
34190 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
341a0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
341b0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
341c0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
341d0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
341e0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
341f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34200 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
34210 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
34220 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
34230 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
34240 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
34250 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
34260 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
34270 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
34280 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
34290 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
342a0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
342b0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
342c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
342d0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
342e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
342f0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
34300 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
34310 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
34320 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
34330 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
34340 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
34350 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
34360 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
34370 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
34380 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
34390 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
343a0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
343b0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
343c0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
343d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
343e0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
343f0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
34400 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34410 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
34420 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
34430 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
34440 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
34450 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
34460 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
34470 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
34480 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
34490 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
344a0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
344b0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
344c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
344d0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
344e0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
344f0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
34500 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
34510 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
34520 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
34530 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
34540 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
34550 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
34560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34570 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34580 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
34590 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
345a0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
345b0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
345c0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
345d0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
345e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
345f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
34600 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
34610 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
34620 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
34630 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
34640 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
34650 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
34660 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
34670 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
34680 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
34690 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
346a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
346b0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
346c0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
346d0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
346e0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
346f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
34700 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
34710 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
34720 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
34730 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
34740 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
34750 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
34760 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
34770 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
34780 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
34790 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
347a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
347b0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
347c0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
347d0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
347e0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
347f0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
34800 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
34810 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
34820 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34830 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
34840 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
34850 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
34860 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
34870 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
34880 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
34890 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
348a0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
348b0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
348c0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
348d0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
348e0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
348f0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
34900 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
34910 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
34920 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
34930 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
34940 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
34950 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
34960 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
34970 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
34980 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
34990 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
349a0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
349b0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
349c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
349d0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
349e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
349f0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
34a00 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
34a10 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
34a20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
34a30 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
34a40 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
34a50 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
34a60 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
34a70 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
34a80 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
34a90 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
34aa0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
34ab0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
34ac0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34ad0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
34ae0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
34af0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
34b00 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
34b10 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34b20 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
34b30 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
34b40 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
34b50 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
34b60 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
34b70 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
34b80 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
34b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34ba0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
34bb0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
34bc0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
34bd0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
34be0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34bf0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
34c00 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
34c10 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34c20 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
34c30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
34c40 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
34c50 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
34c60 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
34c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34c90 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
34ca0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
34cb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34cc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34cd0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
34ce0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
34cf0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
34d00 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34d10 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
34d20 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
34d30 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
34d40 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
34d50 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
34d60 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
34d70 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
34d80 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
34d90 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
34da0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
34db0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
34dc0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
34dd0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
34de0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
34df0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
34e00 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
34e10 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34e20 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
34e30 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
34e40 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
34e50 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
34e60 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
34e70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34e80 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
34e90 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
34ea0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
34eb0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
34ec0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
34ed0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
34ee0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
34ef0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
34f00 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
34f10 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
34f20 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
34f30 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
34f40 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
34f50 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
34f60 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
34f70 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
34f80 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
34f90 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
34fa0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
34fb0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
34fc0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
34fd0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
34fe0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
34ff0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
35000 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
35010 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35020 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
35030 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
35040 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35050 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
35060 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35070 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35080 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35090 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
350a0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
350b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
350c0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
350d0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
350e0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
350f0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
35100 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
35110 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
35120 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35130 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
35140 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
35150 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
35160 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
35170 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35180 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
35190 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
351a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
351b0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
351c0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
351d0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
351e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
351f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35200 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
35210 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
35220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35230 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35240 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
35260 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
35270 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
35280 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
35290 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
352a0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
352b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
352c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
352d0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
352e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
352f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35300 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35310 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
35320 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
35330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35340 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
35350 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35360 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
35370 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35380 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35390 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
353a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
353b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
353c0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
353d0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
353e0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
353f0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35400 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35410 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
35420 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35430 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
35440 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
35450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35460 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
35470 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
35480 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
35490 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
354a0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
354b0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
354c0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
354d0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
354e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
354f0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
35500 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
35510 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
35520 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
35530 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
35540 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
35550 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
35560 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
35570 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
35580 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
35590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
355a0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
355b0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
355c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
355d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
355e0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
355f0 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
35600 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
35610 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
35620 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
35630 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35640 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
35650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35660 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
35670 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
35680 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
35690 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
356a0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
356b0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
356c0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
356d0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
356e0 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
356f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35700 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
35710 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35720 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
35730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35740 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
35750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
35760 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
35770 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
35780 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
35790 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
357a0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
357b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
357c0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
357d0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
357e0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
357f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
35800 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
35810 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
35820 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
35830 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
35840 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
35850 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
35860 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
35870 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
35880 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
35890 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
358a0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
358b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
358c0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
358d0 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
358e0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
358f0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
35900 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
35910 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
35920 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
35930 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35940 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
35950 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
35960 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
35970 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
35980 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
35990 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
359a0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
359b0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
359c0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
359d0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
359e0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
359f0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
35a00 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
35a10 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
35a20 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
35a30 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35a40 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
35a50 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
35a60 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
35a70 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
35a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35a90 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
35aa0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
35ab0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
35ac0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
35ad0 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
35ae0 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
35af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
35b00 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
35b10 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
35b20 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
35b30 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
35b40 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
35b50 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
35b60 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
35b70 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
35b80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
35b90 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
35ba0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
35bb0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
35bc0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
35bd0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
35be0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
35bf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35c00 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
35c10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35c20 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
35c30 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
35c40 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
35c50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35c60 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
35c70 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
35c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
35c90 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
35ca0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
35cb0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
35cc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35cd0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
35ce0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
35cf0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35d00 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
35d10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
35d20 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
35d30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35d40 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
35d50 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
35d60 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
35d70 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
35d80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
35d90 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
35da0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
35db0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35dc0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
35dd0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
35de0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
35df0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35e00 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
35e10 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
35e20 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
35e30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
35e40 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
35e50 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
35e60 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
35e70 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
35e80 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
35e90 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
35ea0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
35eb0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
35ec0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35ed0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
35ee0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
35ef0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
35f00 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
35f10 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
35f20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35f30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
35f40 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
35f50 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
35f60 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
35f70 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
35f80 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
35f90 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
35fa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35fb0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
35fc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
35fd0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
35fe0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
35ff0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
36000 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
36010 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
36020 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
36030 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36040 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
36050 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36060 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
36070 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
36080 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
36090 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
360a0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
360b0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
360c0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
360d0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
360e0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
360f0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
36100 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
36110 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
36120 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
36130 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
36140 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
36150 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
36160 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
36170 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
36180 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
36190 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
361a0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
361b0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
361c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
361d0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
361e0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
361f0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
36200 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
36210 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
36220 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
36230 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
36240 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
36250 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36260 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
36270 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
36280 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
36290 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
362a0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
362b0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
362c0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
362d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
362e0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
362f0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
36300 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36310 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
36320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36330 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
36340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
36350 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36360 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36370 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
36380 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
36390 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
363a0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
363b0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
363c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
363d0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
363e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
363f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
36400 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
36410 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
36420 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
36430 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
36440 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
36450 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
36460 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
36470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36480 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
36490 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
364a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
364b0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
364c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
364d0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
364e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
364f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
36500 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
36510 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
36520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36530 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36540 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36550 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
36560 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
36570 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
36580 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
36590 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
365a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
365b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
365c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
365d0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
365e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
365f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36600 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
36610 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
36620 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
36630 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
36640 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
36650 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
36660 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
36670 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
36680 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
36690 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
366a0 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
366b0 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
366c0 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
366d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
366e0 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
366f0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
36700 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
36710 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
36720 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
36730 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
36740 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
36750 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
36760 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
36770 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
36780 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
36790 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
367a0 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
367b0 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
367c0 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
367d0 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
367e0 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
367f0 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
36800 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
36810 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
36820 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
36830 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
36840 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
36850 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
36860 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
36870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36880 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
36890 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
368a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
368b0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
368c0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
368d0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
368e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
368f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
36900 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
36910 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36920 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
36930 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
36940 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
36950 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
36960 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36970 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
36980 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
36990 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
369a0 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
369b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
369c0 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
369d0 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
369e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
369f0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
36a00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36a10 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
36a20 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
36a30 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36a40 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
36a50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
36a70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
36a80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
36a90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
36aa0 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
36ab0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36ac0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  .*/.sqlite3_valu
36ad0 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
36ae0 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
36af0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
36b00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
36b10 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
36b20 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
36b30 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
36b40 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
36b50 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
36b60 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
36b70 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
36b80 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
36b90 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
36ba0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
36bb0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
36bc0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
36bd0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
36be0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
36bf0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
36c00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36c10 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
36c20 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
36c30 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
36c40 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
36c50 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
36c60 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
36c70 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
36c80 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
36c90 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
36ca0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
36cb0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
36cc0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
36cd0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
36ce0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
36cf0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
36d00 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
36d10 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
36d20 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
36d30 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
36d40 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
36d50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
36d60 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
36d70 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
36d80 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
36d90 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
36da0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
36db0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
36dc0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
36dd0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
36de0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
36df0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
36e00 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
36e10 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
36e20 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
36e30 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
36e40 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
36e50 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
36e60 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
36e70 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
36e80 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
36e90 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
36ea0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
36eb0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
36ec0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
36ed0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
36ee0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
36ef0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
36f00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
36f10 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
36f20 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
36f30 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
36f40 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
36f50 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
36f60 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
36f70 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
36f80 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
36f90 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
36fa0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
36fb0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
36fc0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
36fd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36fe0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
36ff0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
37000 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
37010 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
37020 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
37030 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
37040 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
37050 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
37060 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37070 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
37080 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
37090 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
370a0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
370b0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
370c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
370d0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
370e0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
370f0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
37100 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
37110 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
37120 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37130 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
37140 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
37150 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
37160 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
37170 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
37180 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
37190 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
371a0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
371b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
371c0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
371d0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
371e0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
371f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
37200 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
37210 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
37220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
37230 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
37240 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
37250 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37260 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
37270 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
37280 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
37290 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
372a0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
372b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
372c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
372d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
372e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
372f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
37300 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
37310 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
37320 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
37330 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37340 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
37350 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
37360 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
37370 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
37380 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
37390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
373a0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
373b0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
373c0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
373d0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
373e0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
373f0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
37400 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
37410 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
37420 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
37430 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
37440 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
37450 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
37460 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
37470 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
37480 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
37490 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
374a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
374b0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
374c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
374d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
374e0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
374f0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
37500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37510 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37520 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
37530 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
37540 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
37550 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
37560 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
37570 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
37580 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
37590 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
375a0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
375b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
375c0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
375d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
375e0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
375f0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
37600 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37610 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
37620 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
37630 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
37640 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
37650 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
37660 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37670 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
37680 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
37690 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
376a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
376b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
376c0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
376d0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
376e0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
376f0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
37700 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
37710 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
37720 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37730 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
37740 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
37750 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
37760 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
37770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
37780 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
37790 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
377a0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
377b0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
377c0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
377d0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
377e0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
377f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
37800 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
37810 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
37820 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
37830 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
37840 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
37850 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
37860 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
37870 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
37880 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
37890 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
378a0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
378b0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
378c0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
378d0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
378e0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
378f0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
37900 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
37910 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
37920 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
37930 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
37940 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
37950 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
37960 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
37970 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
37980 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
37990 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
379a0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
379b0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
379c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
379d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
379e0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
379f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37a00 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
37a10 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
37a20 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
37a30 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
37a40 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
37a50 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
37a60 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
37a70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37a80 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
37a90 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
37aa0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
37ab0 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
37ac0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
37ad0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
37ae0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
37af0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
37b00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
37b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37b20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
37b30 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
37b40 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
37b50 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
37b60 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
37b70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37b80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37b90 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
37ba0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
37bb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
37bc0 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
37bd0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
37be0 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
37bf0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
37c00 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
37c10 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
37c20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
37c30 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
37c40 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
37c50 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
37c60 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
37c70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
37c80 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
37c90 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
37ca0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
37cb0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
37cc0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
37cd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
37ce0 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
37cf0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
37d00 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
37d10 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
37d20 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
37d30 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
37d40 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
37d50 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
37d60 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
37d70 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
37d80 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
37d90 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
37da0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
37db0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
37dc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
37dd0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
37de0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
37df0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
37e00 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
37e10 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
37e20 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
37e30 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
37e40 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
37e50 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
37e60 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
37e70 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
37e80 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
37e90 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
37ea0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
37eb0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
37ec0 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
37ed0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
37ee0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
37ef0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
37f00 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
37f10 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
37f20 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
37f30 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
37f40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
37f50 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
37f60 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
37f70 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
37f80 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
37f90 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
37fa0 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
37fb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
37fc0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
37fd0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
37fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
37ff0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
38000 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
38010 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
38020 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
38030 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
38040 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
38050 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
38060 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
38070 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
38080 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
38090 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
380a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
380b0 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
380c0 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
380d0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
380e0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
380f0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
38100 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
38110 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
38120 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
38130 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
38140 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
38150 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
38160 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
38170 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
38180 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
38190 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
381a0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
381b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
381c0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
381d0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
381e0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
381f0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
38200 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
38210 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
38220 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
38230 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
38240 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
38250 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
38260 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
38270 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
38280 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
38290 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
382a0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
382b0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
382c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
382d0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
382e0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
382f0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
38300 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
38310 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
38320 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
38330 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
38340 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
38350 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
38360 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
38370 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
38380 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
38390 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
383a0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
383b0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
383c0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
383d0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
383e0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
383f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
38400 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
38410 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
38420 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
38430 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
38440 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
38450 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
38460 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
38470 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
38480 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
38490 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
384a0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
384b0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
384c0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
384d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
384e0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
384f0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
38500 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
38510 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
38520 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
38530 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL Function.** 
38540 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38550 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68  context.**.** Th
38560 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
38570 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
38580 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
38590 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
385a0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
385b0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
385c0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
385d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
385e0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
385f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38600 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
38610 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
38620 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
38630 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
38640 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
38650 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
38660 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
38670 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
38680 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
38690 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
386a0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
386b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
386c0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
386d0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
386e0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
386f0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
38700 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
38710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38720 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
38730 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
38740 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
38750 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
38760 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38770 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
38780 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
38790 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
387a0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
387b0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
387c0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
387d0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
387e0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
387f0 65 72 2e