/ Hex Artifact Content
Login

Artifact 533fbbd82130f0edc01396f1e53a698cdf1b590e:


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 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8580: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8590: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
85a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
85b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
85c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
85d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
85e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
85f0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8600: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8610: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8620: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8630: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8640: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8650: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8660: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8670: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8680: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8690: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
86a0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
86b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
86c0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
86d0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
86e0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
86f0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8700: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8710: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8720: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8730: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8740: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8760: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8770: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8780: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8790: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
87a0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
87b0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
87c0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
87d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
87e0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
87f0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8800: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8810: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8820: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8830: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8840: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8850: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8860: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8870: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8890: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
88a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
88b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
88c0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
88d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
88e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
88f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
8900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
8910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
89b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
89c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
89d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
89e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
89f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8a00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8a10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8a20: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8a30: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8a40: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
8a50: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8a60: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a70: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a80: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8a90: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8aa0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8ab0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8ac0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8ae0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8b00: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8b10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8b20: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8b30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8b40: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8b50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8b60: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8b70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8b80: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
8b90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ba0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8bb0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8bc0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
8bd0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
8be0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8bf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8c00: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8c10: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8c20: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8c30: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8c40: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
8c50: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
8c60: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8c70: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8c80: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8c90: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8ca0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8cb0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8cc0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8cd0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8ce0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8cf0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8d00: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8d10: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8d20: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8d40: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
8d50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
8d60: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8d90: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8da0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8db0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8dc0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8dd0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8de0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8df0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8e00: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8e10: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8e20: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8e30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8e40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8e60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8e80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8ea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8eb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8ec0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8ed0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ee0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8ef0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
8f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8f10: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8f20: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8f30: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
8f40: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
8f50: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
8f60: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
8f70: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
8f80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8f90: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8fa0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
8fb0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
8fc0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
8fd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
8fe0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
8ff0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9000: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9010: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9020: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9030: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9040: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9060: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9070: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9080: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9090: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
90a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
90b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
90c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
90d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
90e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
90f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9100: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9110: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9120: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9130: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9140: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9150: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9160: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9170: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9180: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9190: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
91a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
91b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
91c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
91d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
91e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
91f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9200: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9210: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9220: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9230: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9240: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9250: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9260: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9280: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9290: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
92a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
92b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
92c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
92d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
92e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
92f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9300: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9320: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9330: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9340: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9350: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9360: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9370: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9380: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9390: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
93a0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
93b0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
93c0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
93d0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
93e0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
93f0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9400: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9410: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9420: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9430: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9440: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9450: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9460: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9470: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9480: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9490: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
94a0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
94b0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
94c0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
94d0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
94e0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
94f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9500: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9510: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9520: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9530: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9540: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9550: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9560: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9570: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9580: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9590: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
95a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
95b0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
95c0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
95d0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
95e0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
95f0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9610: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9620: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9630: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9640: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9650: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9660: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9680: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9690: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
96a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
96b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
96c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
96d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
96e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
96f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9700: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9710: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9720: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9730: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9740: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9750: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9760: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9770: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9780: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9790: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
97a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
97b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
97c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
97d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
97e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
97f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9800: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9810: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9820: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9830: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9840: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9850: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9860: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9870: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9880: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
98a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
98b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
98c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
98d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
98e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
98f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
9900: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
9910: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
9920: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
9930: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
9940: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
9950: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
9960: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
9970: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
9980: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
9990: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
99a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
99b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
99c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
99d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
99e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
99f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
9a00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
9a10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
9a20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
9a40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9a50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
9a60: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
9a70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9a80: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9aa0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9ab0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9ac0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9ad0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
9ae0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
9af0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9b00: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9b10: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9b20: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9b30: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9b40: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9b50: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9b60: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9b70: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9b80: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9b90: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9bb0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9bc0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9bd0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9be0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9bf0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9c00: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9c10: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9c20: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9c30: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9c40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9c50: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9c60: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9c70: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9c80: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9ca0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9cb0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9cc0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9ce0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9cf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9d00: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9d10: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9d20: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9d30: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9d40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9d50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9d60: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9d70: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9d80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9d90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9da0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9db0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9dc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9dd0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9de0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
9df0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9e00: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9e10: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9e20: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9e30: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9e40: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9e50: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9e60: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9e70: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9e80: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9e90: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9ea0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9eb0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9ec0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9ed0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ee0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9ef0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
9f00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9f10: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9f20: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9f30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9f40: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9f50: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9f60: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9f70: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9f80: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9f90: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9fa0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9fb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9fc0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9fd0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9fe0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9ff0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a000: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a010: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a020: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a030: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a040: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a050: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a060: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a070: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a080: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a090: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a0a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a0b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a0d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a0e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a0f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a100: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a110: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a120: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a130: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a140: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a150: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a160: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a170: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a180: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a190: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a1a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a1b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a1c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a1d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a1e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a1f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a200: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a210: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a220: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a230: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a240: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a250: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a260: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a270: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a290: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a2a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a2b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a2c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a2d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a2e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
a300: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
a310: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
a320: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
a330: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
a340: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
a350: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
a360: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
a370: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
a380: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a390: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
a3a0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a3b0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
a3c0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
a3d0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
a3e0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
a3f0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
a400: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
a410: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
a420: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
a430: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
a440: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a450: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
a460: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
a470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a480: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
a490: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
a4a0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
a4b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a4c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
a4d0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
a4e0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
a4f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
a500: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
a510: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
a520: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
a530: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
a540: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
a550: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a560: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
a570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
a580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a590: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
a5a0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
a5b0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
a5c0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
a5d0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
a5e0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
a5f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
a610: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
a620: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
a630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
a640: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a650: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
a660: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a690: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a6b0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
a6c0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
a6d0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
a6e0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
a6f0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
a700: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
a710: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
a720: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
a730: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
a740: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
a750: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
a760: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
a770: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
a780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
a790: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
a7a0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
a7b0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
a7c0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
a7d0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
a7f0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
a800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
a810: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
a820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a830: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
a840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a850: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
a860: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
a870: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
a880: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
a890: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a8a0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
a8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
a8c0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
a8d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
a8e0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
a8f0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
a900: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
a910: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
a920: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
a930: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
a940: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
a950: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
a960: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
a970: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
a980: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
a990: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
a9a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
a9b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
a9c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a9e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
a9f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
aa00: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
aa20: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
aa30: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
aa40: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
aa50: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
aa60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
aa70: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
aa80: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
aa90: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
aaa0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
aab0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
aac0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
aad0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
aae0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
aaf0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ab00: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ab10: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ab20: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ab30: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ab40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ab50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ab60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ab70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ab80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ab90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
abb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
abc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
abd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
abe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
abf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ac00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ac10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ac20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ac30: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ac40: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
ac50: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
ac60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ac70: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
ac80: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ac90: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
aca0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
acb0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
acc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
acd0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ace0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
acf0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ad00: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ad10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ad20: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ad30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ad40: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
ad50: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
ad60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ad70: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
ad80: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
ad90: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
ada0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
adb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
adc0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
add0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ade0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
adf0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ae00: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ae10: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ae20: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ae30: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ae40: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ae50: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ae60: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ae70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ae80: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ae90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
aea0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
aeb0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
aec0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
aed0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
aee0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
aef0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
af00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
af10: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
af20: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
af30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
af40: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
af50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
af60: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
af70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
af80: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
af90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
afa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afc0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
afd0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
afe0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
aff0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b000: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b010: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b020: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b030: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b040: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b050: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b060: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b070: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b080: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b090: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b0a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b0b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b0c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b0d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b0e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b0f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b100: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b110: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b120: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b130: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b140: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b150: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b160: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b170: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b190: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b1b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b1c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b1d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b1e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b1f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b200: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b210: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b220: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b230: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b240: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b260: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b270: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b280: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b290: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b2a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b2c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b2d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b2e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b300: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
b310: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
b320: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b330: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
b340: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
b350: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
b360: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
b370: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
b380: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
b390: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
b3a0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
b3b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
b3c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3d0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
b3e0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
b3f0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
b400: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
b410: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
b420: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
b430: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b440: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
b450: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
b460: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
b470: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
b480: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
b490: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
b4a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
b4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b4c0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
b4d0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
b4e0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
b4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
b500: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
b510: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
b520: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
b530: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
b540: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
b550: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
b560: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
b570: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
b580: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
b590: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
b5a0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
b5b0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
b5c0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
b5d0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
b5e0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
b5f0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
b600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
b610: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
b620: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
b630: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
b640: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
b650: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b660: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b670: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
b680: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
b690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b6a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b6b0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
b6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b6d0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
b6e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
b6f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
b700: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b710: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b720: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
b730: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
b740: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
b750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b760: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
b770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
b780: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
b790: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b7a0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
b7b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
b7c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
b7d0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b7e0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
b7f0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b800: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
b810: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
b820: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
b830: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
b840: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
b850: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
b860: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
b870: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
b880: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
b890: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
b8a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b8b0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
b8c0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
b8d0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
b8e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b8f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
b900: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
b910: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
b920: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b930: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
b940: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
b950: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
b960: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
b970: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
b980: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
b990: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
b9a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
b9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
b9c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
b9d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
b9e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
b9f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
ba00: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ba10: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
ba20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba30: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
ba40: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
ba50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ba60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ba70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ba80: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
ba90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
baa0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
bab0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
bac0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
bad0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
bae0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
baf0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
bb00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
bb10: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
bb20: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
bb30: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
bb40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
bb50: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
bb60: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
bb70: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
bb80: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
bb90: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
bba0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bbc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbd0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
bc00: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
bc10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
bc20: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
bc30: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
bc40: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
bc50: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
bc60: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
bc70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc80: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
bc90: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
bca0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
bcb0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
bcc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
bcd0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
bce0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
bcf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bd00: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
bd20: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
bd30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd40: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
bd50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
bd60: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
bd80: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
bd90: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
bda0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
bdb0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
bdc0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
bdd0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
bde0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
bdf0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
be00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
be20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
be30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
be40: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
be50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
be60: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
be70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
be80: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
be90: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
bea0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
beb0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
bec0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
bed0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
bee0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
bef0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bf00: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
bf10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
bf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
bf40: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
bf50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf60: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
bf70: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
bf80: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
bf90: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
bfa0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
bfb0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
bfc0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
bfd0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
bfe0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
bff0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c000: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c020: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c030: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c040: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c050: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c060: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c090: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c0a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c0c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c0d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c0e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c0f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c100: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c110: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c120: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c130: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c140: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c150: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c160: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c170: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c180: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c190: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c1a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c1b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c1c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c1d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c1e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c1f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c200: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c210: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c220: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c230: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c240: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c250: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c260: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c270: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c280: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c290: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c2a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c2c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c2d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c2e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c2f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c310: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c320: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c340: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c350: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c360: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c370: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c380: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
c390: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c3a0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
c3b0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
c3c0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
c3d0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
c3e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
c3f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
c400: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
c410: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
c420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c430: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
c440: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
c450: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c460: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c470: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c480: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c490: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c4a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c4c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c4d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c4e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c4f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c500: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c510: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c520: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c530: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
c540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c550: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
c560: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c570: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
c580: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
c5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
c5b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
c5c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c5d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
c5e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
c5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
c600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
c610: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
c620: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c630: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c640: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c670: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
c680: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
c690: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
c6a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
c6b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
c6c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
c6d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
c6e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c6f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
c700: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
c710: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
c720: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
c730: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
c740: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
c750: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
c760: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
c770: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
c780: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c790: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
c7a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
c7b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
c7c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
c7d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
c7e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c7f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
c800: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
c810: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c820: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c830: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
c840: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
c850: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
c860: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
c870: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
c880: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
c890: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
c8a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
c8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
c8c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
c8d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
c8e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
c8f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
c900: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
c910: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
c920: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
c930: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
c940: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
c950: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
c960: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c970: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
c980: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
c990: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c9a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
c9b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
c9c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
c9d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
c9e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
c9f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
ca00: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
ca10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ca20: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ca30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ca40: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ca50: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ca60: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ca70: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ca80: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
ca90: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
caa0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
cab0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
cac0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
cad0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
cae0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
caf0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
cb00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
cb10: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
cb20: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
cb30: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
cb40: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
cb50: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
cb60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
cb70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cb80: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
cb90: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
cba0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
cbb0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
cbc0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
cbd0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
cbe0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
cbf0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
cc00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
cc10: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
cc20: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
cc30: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
cc40: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cc50: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
cc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
cc70: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
cc80: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
cc90: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
cca0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
ccb0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
ccc0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
ccd0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
cce0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
ccf0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
cd00: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
cd10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
cd20: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
cd30: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
cd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
cd50: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
cd60: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
cd70: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
cd80: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cd90: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
cda0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
cdb0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
cdc0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
cdd0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
cde0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
cdf0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
ce00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ce10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
ce20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ce30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
ce40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
ce50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
ce60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
ce80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
ce90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cea0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ceb0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cec0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ced0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cee0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cef0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cf00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cf10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cf20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cf30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
cf40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
cf50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
cf60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
cf70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
cf80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
cf90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
cfa0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
cfb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
cfc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
cfd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
cfe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
cff0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d000: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d010: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d020: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d030: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d040: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d050: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d060: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d070: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d080: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d0a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d0b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d0c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d0d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d0e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d0f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d100: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d110: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d120: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d130: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d140: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d150: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d160: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d170: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d180: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d190: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d1a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d1b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d1c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d1d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d1e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d1f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d200: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d210: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d220: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d230: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d240: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d260: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d270: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d280: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d2a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d2b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d2c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d2d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d2e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d2f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
d300: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
d310: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
d320: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
d330: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
d340: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
d350: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
d360: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
d370: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
d380: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
d390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
d3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
d3b0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
d3c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
d3d0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
d3e0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
d3f0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
d400: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
d410: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
d420: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
d430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d440: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
d450: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
d460: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
d470: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d480: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d490: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
d4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
d4b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
d4c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
d4d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
d4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d500: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
d510: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d520: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d530: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d540: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d550: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d560: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d570: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d590: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d5a0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d5b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d5c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d5d0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d5e0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d5f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d600: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d610: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d620: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d630: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d640: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d650: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d660: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d670: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d680: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d6a0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d6b0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d6c0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d6d0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d6e0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d6f0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d700: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d710: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d720: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d730: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d740: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d750: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d760: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d770: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d780: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d790: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d7a0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
d7b0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d7c0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d7d0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d7e0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d7f0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d800: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d810: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d820: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d830: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d850: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d860: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d870: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d880: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d890: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d8a0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d8b0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
d8c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
d8d0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
d8e0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
d8f0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
d900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d910: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
d920: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d930: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d940: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
d950: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
d960: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d970: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d980: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d990: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d9a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d9b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d9c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d9d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
d9e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
d9f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
da00: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
da10: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
da20: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
da30: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da50: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
da60: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
da70: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
da80: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
da90: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
daa0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
dab0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
dac0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
dae0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
daf0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
db00: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
db10: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
db20: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
db30: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
db40: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
db50: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
db60: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
db70: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
db80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db90: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
dba0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
dbb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dbc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dbd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dbe0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dbf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
dc30: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
dc40: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
dc50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
dc60: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
dc70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
dc80: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
dc90: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
dca0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
dcb0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
dcc0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
dcd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dce0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
dcf0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dd00: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dd10: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dd20: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dd30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dd40: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dd50: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
dd60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
dd70: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
dd80: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
dd90: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
dda0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
ddb0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
ddc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
ddd0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
dde0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
ddf0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
de00: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
de10: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
de20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de30: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
de40: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
de50: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
de60: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
de70: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
de80: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
de90: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
dea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
deb0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
dec0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
ded0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
dee0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
def0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
df00: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
df10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
df20: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
df30: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
df40: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
df50: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df60: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
df70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
df80: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
df90: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
dfa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
dfb0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
dfc0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
dfd0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
dfe0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
dff0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e000: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e010: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e020: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e030: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e040: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e050: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e060: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e070: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e080: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e090: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e0a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e0b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e0c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e0d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e0e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e0f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e100: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e110: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e120: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e130: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e150: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e160: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e170: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e180: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e190: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e1a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e1b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e1c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e1d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e1e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e200: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e210: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e220: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e230: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e240: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e250: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e260: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e270: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e280: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e290: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e2a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e2b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e2d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e2e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e2f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e300: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e310: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e320: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
e330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
e340: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
e350: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
e360: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
e370: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e380: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
e390: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
e3a0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
e3b0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
e3c0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
e3d0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
e3e0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
e3f0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
e400: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e410: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
e420: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e430: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
e440: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
e450: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
e460: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
e470: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
e480: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
e490: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
e4a0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
e4b0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
e4c0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e4f0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
e500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
e510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
e520: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
e530: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
e540: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e550: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
e560: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e570: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
e580: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e590: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e5a0: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
e5b0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e5c0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
e5d0: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
e5e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e5f0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
e600: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
e610: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
e620: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
e630: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
e640: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
e650: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
e660: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
e670: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
e680: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
e690: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
e6a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e6b0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
e6c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e6d0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e6e0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e6f0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e700: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
e710: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
e720: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
e730: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e740: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
e750: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
e760: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
e770: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
e780: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
e790: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
e7a0: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
e7b0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
e7c0: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
e7d0: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
e7e0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
e7f0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
e800: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
e810: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e820: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
e830: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
e840: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e850: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e860: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
e870: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
e880: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e890: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
e8a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e8b0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
e8c0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
e8d0: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
e8e0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
e8f0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
e900: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
e910: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
e920: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
e930: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
e940: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
e950: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
e960: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
e970: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
e980: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
e990: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
e9a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
e9b0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
e9c0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e9d0: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
e9e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e9f0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
ea00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
ea10: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
ea20: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
ea30: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
ea40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ea50: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
ea60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ea70: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
ea80: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
ea90: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
eaa0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
eab0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
eac0: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
ead0: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
eae0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
eaf0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
eb00: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
eb10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
eb20: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
eb30: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
eb40: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
eb50: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
eb60: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
eb70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
eb80: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
eb90: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
eba0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ebb0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
ebc0: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
ebd0: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
ebe0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
ebf0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
ec00: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
ec10: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
ec20: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
ec30: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
ec40: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
ec50: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
ec60: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
ec70: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
ec80: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
ec90: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
eca0: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
ecb0: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
ecc0: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
ecd0: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
ece0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
ecf0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
ed00: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
ed10: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
ed20: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
ed30: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
ed40: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
ed50: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
ed60: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
ed70: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
ed80: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
ed90: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
eda0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
edb0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
edc0: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
edd0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
ede0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
edf0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
ee00: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
ee10: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
ee20: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
ee30: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
ee40: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
ee50: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
ee60: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
ee70: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
ee80: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
ee90: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
eea0: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
eeb0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
eec0: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
eed0: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
eee0: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
eef0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ef00: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
ef10: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
ef20: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
ef30: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
ef40: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
ef50: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
ef60: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
ef70: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ef80: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
ef90: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
efa0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
efb0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
efc0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
efd0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
efe0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
eff0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f000: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
f010: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
f020: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
f030: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
f040: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
f050: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
f060: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
f070: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
f080: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
f090: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
f0a0: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
f0b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
f0c0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
f0d0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
f0e0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
f0f0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
f100: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
f110: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
f120: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
f130: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
f140: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
f150: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f160: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
f170: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
f180: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
f190: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
f1a0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
f1b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f1c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
f1d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
f1e0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
f1f0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
f200: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
f210: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
f220: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
f230: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
f240: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
f250: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
f260: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
f270: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
f280: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
f290: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
f2a0: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
f2b0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
f2c0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
f2d0: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
f2e0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
f2f0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
f300: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
f310: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
f320: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
f330: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f340: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
f350: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f360: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f370: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f380: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f390: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
f3a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
f3b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f3c0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f3d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
f3e0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
f3f0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
f400: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
f410: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
f420: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
f430: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
f440: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
f450: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f460: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
f470: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
f480: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f490: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
f4a0: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
f4b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4c0: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
f4d0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
f4e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f4f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
f500: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
f510: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
f520: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f530: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
f540: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
f550: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
f560: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
f570: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
f580: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
f590: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
f5a0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
f5b0: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
f5c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
f5d0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
f5e0: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
f5f0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f600: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
f610: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
f620: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f630: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f640: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f650: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f660: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f670: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
f680: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
f690: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
f6a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f6b0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
f6c0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
f6d0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
f6e0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
f6f0: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
f700: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
f710: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
f720: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
f730: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
f740: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
f750: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
f760: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
f770: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
f780: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
f790: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
f7a0: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
f7b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f7c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
f7d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
f7e0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
f7f0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
f800: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
f810: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
f820: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
f830: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
f840: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
f850: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
f860: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f870: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
f880: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
f890: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
f8a0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
f8b0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
f8c0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
f8d0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f8e0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
f8f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f900: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f910: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
f920: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
f930: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
f940: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
f950: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
f960: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f970: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
f980: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f990: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
f9a0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
f9b0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
f9c0: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
f9d0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
f9e0: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
f9f0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
fa00: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
fa10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fa20: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
fa30: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fa40: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
fa50: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
fa60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
fa70: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
fa80: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
fa90: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
faa0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
fab0: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
fac0: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
fad0: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
fae0: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
faf0: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
fb00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fb10: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
fb20: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fb30: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
fb40: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
fb50: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
fb60: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
fb70: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
fb80: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
fb90: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
fba0: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
fbb0: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
fbc0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
fbd0: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
fbe0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
fbf0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
fc00: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
fc10: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
fc20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
fc30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fc40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
fc50: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
fc60: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
fc70: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
fc80: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
fc90: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
fca0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
fcb0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
fcc0: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
fcd0: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
fce0: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
fcf0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fd00: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
fd10: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
fd20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fd30: 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
fd40: 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
fd50: 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
fd60: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
fd70: 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
fd80: 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
fd90: 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
fda0: 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
fdb0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
fdc0: 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
fdd0: 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
fde0: 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
fdf0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
fe00: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
fe10: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
fe20: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
fe30: 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
fe40: 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
fe50: 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
fe70: 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
fe80: 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
fe90: 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
fea0: 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
feb0: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
fec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
fed0: 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
fee0: 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
fef0: 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
ff00: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
ff10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
ff20: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
ff30: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
ff40: 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
ff50: 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
ff60: 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
ff70: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
ff80: 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
ff90: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
ffa0: 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
ffb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
ffc0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ffd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
ffe0: 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
fff0: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
10000 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
10010 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
10020 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
10030 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
10040 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
10050 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
10060 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
10070 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
10080 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
10090 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
100a0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
100b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
100c0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
100d0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
100e0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
100f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10100 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
10110 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10120 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
10130 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
10140 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
10150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
10160 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
10170 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10180 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
10190 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
101a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
101b0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
101c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
101d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
101e0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
101f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10210 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
10220 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10230 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10240 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
10250 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
10260 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10280 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
10290 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
102a0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
102b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
102c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
102d0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
102e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
102f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10300 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
10310 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
10320 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10340 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
10350 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
10360 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
10370 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
10380 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10390 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
103a0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
103b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
103c0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
103d0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
103e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
103f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10400 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10410 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
10420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10430 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
10440 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
10450 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
10460 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
10470 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
10480 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10490 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
104a0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
104b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
104c0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
104d0 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
104e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
104f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10500 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
10510 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
10520 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10530 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10550 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
10560 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
10570 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10590 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
105a0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
105b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
105c0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
105d0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
105e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105f0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10600 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10610 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10620 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
10630 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
10640 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10650 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10660 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10670 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10680 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10690 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
106a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106b0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
106c0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
106d0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
106e0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
106f0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
10700 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10710 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10720 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10730 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
10740 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
10750 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10760 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10770 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10780 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10790 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
107a0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
107b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
107c0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
107d0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
107e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
107f0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
10800 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10810 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
10820 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
10830 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
10840 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
10850 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10860 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
10870 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
10880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10890 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
108a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
108b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
108c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
108d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
108e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
108f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10900 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
10910 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
10920 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10930 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
10940 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10950 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
10960 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
10970 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
10980 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
10990 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
109a0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
109b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
109c0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
109d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
109e0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
109f0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
10a00 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
10a10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
10a20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
10a30 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
10a40 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
10a50 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
10a60 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10a70 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
10a80 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
10a90 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
10aa0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
10ab0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
10ac0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
10ad0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
10ae0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
10af0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
10b00 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10b10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10b20 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
10b30 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
10b40 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
10b50 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
10b60 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
10b70 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
10b80 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
10b90 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
10ba0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
10bb0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
10bc0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
10bd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
10be0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
10bf0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
10c00 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
10c10 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
10c20 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
10c30 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
10c40 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
10c50 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
10c60 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
10c70 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
10c80 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
10c90 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
10ca0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
10cb0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
10cc0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
10cd0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
10ce0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
10cf0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
10d00 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10d10 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
10d20 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
10d30 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
10d40 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
10d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
10d60 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10d70 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
10d80 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
10d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10da0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
10db0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
10dc0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
10dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
10de0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10df0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
10e00 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10e10 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
10e20 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
10e30 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
10e40 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
10e50 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
10e60 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
10e70 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
10e80 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
10e90 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
10ea0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10eb0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
10ec0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
10ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10ee0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
10ef0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
10f00 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
10f10 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
10f20 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
10f30 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
10f40 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
10f50 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
10f60 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
10f70 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
10f80 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
10f90 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
10fa0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
10fb0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
10fc0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
10fd0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
10fe0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
10ff0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
11000 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
11010 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
11020 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
11030 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
11040 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
11050 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
11060 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
11070 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
11080 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11090 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
110a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
110b0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
110c0 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
110d0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
110e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
110f0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
11100 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
11110 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
11120 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
11130 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
11140 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
11150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
11160 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
11170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
11180 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
11190 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
111a0 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
111b0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
111c0 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
111d0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
111e0 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
111f0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
11200 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
11210 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
11220 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
11230 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11240 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
11250 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
11260 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
11270 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
11280 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
11290 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
112a0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
112b0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
112c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
112d0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
112e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
112f0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
11300 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11310 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
11320 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
11330 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
11340 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
11350 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
11360 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
11370 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
11380 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
11390 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
113a0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
113b0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
113c0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
113d0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
113e0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
113f0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
11400 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
11410 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
11420 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
11430 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
11440 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
11450 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
11460 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
11470 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
11480 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
11490 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
114a0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
114b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
114c0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
114d0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
114e0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
114f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
11500 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
11510 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
11520 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
11530 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
11540 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
11550 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
11560 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
11570 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
11580 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
11590 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
115a0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
115b0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
115c0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
115d0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
115e0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
115f0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
11600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
11610 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
11620 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
11630 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
11640 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
11650 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
11660 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
11670 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
11680 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11690 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
116a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
116b0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
116c0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
116d0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
116e0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
116f0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
11700 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
11710 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
11720 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
11730 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
11740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11750 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
11760 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
11770 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
11780 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
117a0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
117b0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
117c0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
117d0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
117e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
117f0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
11800 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
11810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11820 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
11830 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
11840 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
11850 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
11860 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
11870 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
11880 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
11890 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
118a0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
118b0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
118c0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
118d0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
118e0 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
118f0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
11900 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
11910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11930 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
11940 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
11950 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
11960 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
11970 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
11980 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
11990 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
119a0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
119b0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
119c0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
119d0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
119e0 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
119f0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
11a00 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
11a10 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
11a20 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
11a30 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
11a40 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
11a50 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
11a60 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
11a70 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
11a80 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
11a90 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
11aa0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
11ab0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
11ac0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
11ad0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
11ae0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
11af0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
11b00 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
11b10 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
11b20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
11b30 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
11b40 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
11b50 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
11b60 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
11b70 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
11b80 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
11b90 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
11ba0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
11bb0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
11bc0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
11bd0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
11be0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
11bf0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
11c00 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
11c10 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
11c20 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
11c30 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
11c40 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
11c50 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
11c60 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
11c70 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11c80 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
11c90 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
11ca0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
11cb0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
11cc0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
11cd0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
11ce0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
11cf0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
11d00 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
11d10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
11d20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
11d30 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
11d40 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
11d50 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
11d60 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11d70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
11d80 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
11d90 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
11da0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11db0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11dc0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
11dd0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
11de0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11df0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
11e00 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
11e10 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
11e20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
11e30 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
11e40 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
11e50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
11e60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11e70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11e80 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
11e90 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
11ea0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
11eb0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
11ec0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
11ed0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
11ee0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
11ef0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
11f00 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
11f10 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
11f20 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11f30 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
11f40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
11f50 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
11f60 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
11f70 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
11f80 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
11f90 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
11fa0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11fb0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
11fc0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
11fd0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
11fe0 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
11ff0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
12000 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
12010 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12020 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
12030 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
12040 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
12050 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
12060 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
12070 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
12080 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
12090 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
120a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
120b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
120c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
120d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
120e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
120f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
12100 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
12110 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
12120 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12130 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
12140 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12150 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
12160 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
12170 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
12180 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
12190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
121a0 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
121b0 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
121c0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
121d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
121e0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
121f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12200 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
12210 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
12220 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
12230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12240 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
12250 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
12260 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
12270 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
12280 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
12290 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
122a0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
122b0 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
122c0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
122d0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
122e0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
122f0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
12300 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
12310 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
12320 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12330 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
12340 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
12350 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
12360 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
12370 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
12380 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
12390 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
123a0 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
123b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
123c0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
123d0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
123e0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
123f0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
12400 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
12410 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
12420 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
12430 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
12440 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
12450 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
12460 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
12470 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
12480 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
12490 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
124a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
124b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
124c0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
124d0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
124e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
124f0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12500 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12510 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12520 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
12530 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12540 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
12550 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
12560 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
12570 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
12580 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
12590 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
125a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
125b0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
125c0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
125d0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
125e0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
125f0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
12600 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12610 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
12620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12630 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
12640 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
12650 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12660 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
12670 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
12680 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
12690 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
126a0 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
126b0 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
126c0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
126d0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
126e0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
126f0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
12700 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
12710 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
12720 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
12730 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
12740 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
12750 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
12760 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
12770 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
12780 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
12790 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
127a0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
127b0 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
127c0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
127d0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
127e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
127f0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
12800 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12810 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
12820 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12830 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
12840 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
12850 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
12860 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12870 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
12880 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
12890 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
128a0 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
128b0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
128c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
128d0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
128e0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
128f0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
12900 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
12910 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
12920 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
12930 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
12940 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
12950 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
12960 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
12970 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12980 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
12990 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
129a0 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
129b0 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
129c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
129d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
129e0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
129f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
12a00 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
12a10 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
12a20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
12a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
12a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
12a50 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
12a60 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
12a70 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
12a80 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
12a90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
12aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12ab0 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
12ac0 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
12ad0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12ae0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12af0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
12b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
12b10 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
12b20 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
12b30 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
12b40 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
12b50 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
12b60 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
12b70 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
12b80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12b90 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
12ba0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
12bb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
12bc0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
12bd0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12be0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
12bf0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
12c00 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
12c10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12c20 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
12c30 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
12c40 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
12c50 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
12c60 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
12c70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12c80 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
12c90 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12ca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12cb0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12cc0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
12cd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12ce0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
12cf0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
12d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12d10 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
12d20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12d30 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
12d40 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
12d50 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
12d60 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
12d70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
12d80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12d90 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
12da0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
12db0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
12dc0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
12dd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
12de0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
12df0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12e00 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12e10 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12e20 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
12e30 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
12e40 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12e50 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
12e60 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
12e70 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
12e80 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
12e90 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12ea0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
12eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
12ec0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
12ed0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
12ee0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
12ef0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12f00 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
12f10 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
12f20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
12f30 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
12f40 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
12f50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
12f60 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
12f70 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
12f80 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
12f90 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
12fa0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
12fb0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
12fc0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
12fd0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
12fe0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
12ff0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
13000 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
13010 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
13020 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
13030 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
13040 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
13050 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
13060 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
13070 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
13080 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
13090 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
130a0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
130b0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
130c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
130d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
130e0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
130f0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
13100 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
13110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13120 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
13130 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
13140 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
13150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
13160 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
13170 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
13180 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
13190 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
131a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
131b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
131c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
131d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
131e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
131f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
13200 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
13210 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13220 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
13230 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13240 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
13250 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
13260 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13270 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
13280 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
13290 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
132a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
132b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
132c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
132d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
132e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
132f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
13300 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
13310 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
13320 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13330 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
13340 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
13350 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
13360 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
13370 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
13380 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
13390 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
133a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
133b0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
133c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
133d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
133e0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
133f0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
13400 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13410 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
13420 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
13430 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
13440 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
13450 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
13460 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
13470 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13480 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
13490 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
134a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
134b0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
134c0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
134d0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
134e0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
134f0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
13500 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
13510 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
13520 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
13530 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
13540 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13550 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13560 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
13570 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
13580 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
13590 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
135a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
135b0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
135c0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
135d0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
135e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
135f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
13600 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13610 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
13620 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
13630 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
13640 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
13650 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
13660 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
13670 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
13680 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13690 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
136a0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
136b0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
136c0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
136d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
136e0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
136f0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
13700 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
13710 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
13720 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
13730 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
13740 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
13750 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
13760 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
13770 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
13780 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
13790 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
137a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
137b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
137c0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
137d0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
137e0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
137f0 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
13800 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
13810 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
13820 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
13830 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
13840 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
13850 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
13860 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
13870 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
13880 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
13890 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
138a0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
138b0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
138c0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
138d0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
138e0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
138f0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13900 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13910 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13920 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13930 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13940 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13950 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13960 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13970 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13980 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13990 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
139a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
139b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
139c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
139d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
139e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
139f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13a00 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13a10 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13a20 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13a30 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13a40 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13a50 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13a60 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13a70 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13a80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13a90 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
13aa0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
13ab0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
13ac0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
13ad0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
13ae0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
13af0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13b00 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13b10 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13b20 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13b30 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13b40 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13b50 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13b60 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13b70 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13b80 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13b90 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
13ba0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
13bb0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
13bc0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
13bd0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
13be0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
13bf0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
13c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
13c10 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
13c20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
13c30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13c40 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
13c50 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
13c60 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
13c70 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
13c80 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
13c90 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
13ca0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
13cb0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
13cc0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
13cd0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
13ce0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
13cf0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
13d00 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
13d10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
13d20 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
13d30 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
13d40 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
13d50 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
13d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
13d70 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
13d80 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
13d90 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
13da0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
13db0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
13dc0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
13dd0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
13de0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
13df0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13e00 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
13e10 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
13e20 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
13e30 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
13e40 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
13e50 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
13e60 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
13e70 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
13e80 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
13e90 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
13ea0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
13eb0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
13ec0 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
13ed0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
13ee0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
13ef0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13f00 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
13f10 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
13f20 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
13f30 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
13f40 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
13f50 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
13f60 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
13f70 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
13f80 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
13f90 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
13fa0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
13fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13fc0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
13fd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
13fe0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
13ff0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
14000 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
14010 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
14020 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14030 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
14040 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
14050 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
14060 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
14070 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
14080 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
14090 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
140a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
140b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
140c0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
140d0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
140e0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
140f0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
14100 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
14110 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
14120 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
14130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14140 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
14150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14160 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
14170 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14180 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
14190 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
141a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
141b0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
141c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
141d0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
141e0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
141f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
14200 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
14210 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
14220 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
14230 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
14240 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
14250 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
14260 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
14270 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
14280 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
14290 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
142a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
142b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
142c0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
142d0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
142e0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
142f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
14300 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
14310 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
14320 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
14330 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
14340 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
14350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14360 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14370 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
14380 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
14390 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
143a0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
143b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
143c0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
143d0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
143e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
143f0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
14400 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
14410 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
14420 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
14430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
14440 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
14450 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
14460 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
14470 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
14480 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14490 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
144a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
144b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
144c0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
144d0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
144e0 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
144f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
14500 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
14510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14520 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
14530 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
14540 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
14550 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
14560 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
14570 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
14580 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14590 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
145a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
145b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
145c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
145d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
145e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
145f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
14600 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
14610 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
14620 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14630 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14640 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14650 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14660 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14670 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14680 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14690 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
146a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
146b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
146c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
146d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
146e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
146f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
14700 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
14710 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
14720 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
14730 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14750 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14770 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14780 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14790 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
147a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
147b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
147c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
147d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
147e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
147f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
14800 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
14810 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14820 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14830 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14840 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14850 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14860 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14870 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14880 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14890 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
148a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
148b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
148c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
148d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
148e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
148f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
14900 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
14910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
14920 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
14930 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14940 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14950 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14960 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14970 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14980 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14990 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
149a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
149b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
149c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
149d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
149e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
149f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
14a00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
14a10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14a20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14a30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14a40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14a50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14a60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14a70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
14a80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
14a90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
14aa0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
14ab0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
14ac0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14ad0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14ae0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14af0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14b00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14b10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14b20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14b30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14b40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14b50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
14b60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
14b70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
14b80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
14b90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
14ba0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
14bb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
14bc0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14bd0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14be0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14bf0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14c00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14c10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14c20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14c30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14c40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14c50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
14c60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14c70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
14c80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14c90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
14ca0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
14cb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
14cc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14cd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14ce0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14cf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14d00 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14d10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14d20 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
14d30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14d40 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
14d50 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
14d60 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
14d70 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
14d80 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
14d90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14da0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
14db0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
14dc0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
14dd0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
14de0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
14df0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
14e00 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
14e10 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
14e20 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
14e30 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
14e40 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
14e50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14e60 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
14e70 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14e80 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
14e90 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14ea0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14eb0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ec0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14ed0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14ee0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14ef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14f00 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14f10 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14f20 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14f30 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14f40 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14f50 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14f60 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14f70 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14f80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14f90 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14fa0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14fb0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14fc0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14fd0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14fe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14ff0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
15000 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
15010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
15020 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
15030 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
15040 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
15050 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
15060 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
15070 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
15080 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
15090 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
150a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
150b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
150c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
150d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
150e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
150f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
15100 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
15110 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
15120 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
15130 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
15140 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
15150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
15160 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
15170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15190 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
151a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
151b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
151c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
151d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
151e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
151f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15200 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15210 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15220 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15230 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15240 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15250 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
15260 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
15270 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
15280 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15290 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
152a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
152b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
152c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
152d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
152e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
152f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15300 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15310 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15320 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
15330 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
15340 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
15350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
15360 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
15370 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
15380 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
15390 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
153a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
153b0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
153c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
153d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
153e0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
153f0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
15400 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
15410 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
15420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15430 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
15440 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
15450 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
15460 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
15470 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
15480 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
15490 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
154a0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
154b0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
154c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
154d0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
154e0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
154f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
15500 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15510 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73  ng..**.** ^(In s
15520 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15530 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
15540 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
15550 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
15560 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
15570 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
15580 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
15590 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
155a0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
155b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
155c0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
155d0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
155e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
155f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
15600 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
15610 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
15620 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
15630 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
15640 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
15650 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
15660 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
15670 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
15680 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
15690 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
156a0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
156b0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
156c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
156d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
156e0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
156f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
15700 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
15710 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
15720 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
15730 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
15740 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
15750 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
15760 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
15770 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
15780 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
15790 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
157a0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
157b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
157c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
157d0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
157e0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
157f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
15800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
15810 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
15820 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
15830 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15840 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
15850 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
15860 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
15870 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
15880 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
15890 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
158a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
158b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
158c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
158d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
158e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
158f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
15900 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
15910 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
15920 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
15930 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15940 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
15950 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
15960 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
15970 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
15980 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
15990 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
159a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
159b0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
159c0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
159d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
159e0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
159f0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
15a00 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
15a10 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
15a20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
15a30 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
15a40 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
15a50 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
15a60 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
15a70 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
15a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
15a90 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
15aa0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
15ab0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
15ac0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
15ad0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
15ae0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
15af0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
15b00 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
15b10 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
15b20 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
15b30 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
15b40 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
15b50 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
15b60 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
15b70 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
15b80 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
15b90 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
15ba0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
15bb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15bc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
15bd0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
15be0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
15bf0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15c00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
15c10 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
15c20 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
15c30 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
15c40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c50 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15c60 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15c70 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15c80 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15c90 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
15ca0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
15cb0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
15cc0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
15cd0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
15ce0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15cf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
15d00 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
15d10 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
15d20 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
15d30 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
15d40 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
15d50 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
15d60 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
15d70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15d80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15d90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15da0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
15db0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
15dc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15dd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
15de0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
15df0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
15e00 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
15e10 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
15e20 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
15e30 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
15e40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15e50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
15e60 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
15e70 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
15e80 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
15e90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15ea0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
15eb0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
15ec0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
15ed0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
15ee0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
15ef0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
15f00 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
15f10 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
15f20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
15f30 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
15f40 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
15f50 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
15f60 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
15f70 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
15f80 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
15f90 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
15fa0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
15fb0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
15fc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
15fd0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
15fe0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
15ff0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
16000 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
16010 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
16020 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
16030 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
16040 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
16050 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
16060 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16070 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
16080 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
16090 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
160a0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
160b0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
160c0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
160d0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
160e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
160f0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
16100 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16110 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
16120 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
16130 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
16140 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
16150 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
16160 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
16170 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
16180 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
16190 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
161a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
161b0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
161c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
161d0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
161e0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
161f0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
16200 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
16210 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
16220 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
16230 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
16240 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
16250 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
16260 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
16270 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
16280 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
16290 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
162a0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
162b0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
162c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
162d0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
162e0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
162f0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
16300 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
16310 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
16320 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
16330 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
16340 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
16350 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
16360 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
16370 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
16380 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
16390 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
163a0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
163b0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
163c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
163d0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
163e0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
163f0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
16400 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
16410 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
16420 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
16430 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
16440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16450 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
16460 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
16470 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
16480 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
16490 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
164a0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
164b0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
164c0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
164d0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
164e0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
164f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
16500 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16510 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
16520 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
16530 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
16540 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
16550 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
16560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16570 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
16580 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
16590 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
165a0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
165b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
165c0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
165d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
165e0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
165f0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
16600 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
16610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
16620 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16630 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16640 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16650 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16660 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16670 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16680 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16690 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
166a0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
166b0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
166c0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
166d0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
166e0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
166f0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16700 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16710 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16720 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16730 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16740 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16750 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16760 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16770 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16780 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16790 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
167a0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
167b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
167c0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
167d0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
167e0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
167f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16800 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
16810 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
16820 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
16830 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
16840 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
16850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16860 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
16870 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
16880 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
16890 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
168a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
168b0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
168c0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
168d0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
168e0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
168f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
16900 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
16910 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16920 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
16930 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
16940 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
16950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
16960 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
16970 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16980 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16990 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
169a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
169b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
169c0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
169d0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
169e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
169f0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
16a00 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
16a10 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
16a20 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
16a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16a40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16a50 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
16a60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
16a70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16a80 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
16a90 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
16aa0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
16ab0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
16ac0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
16ad0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
16ae0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
16af0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
16b00 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
16b10 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
16b20 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
16b30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
16b40 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
16b50 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
16b60 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
16b70 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
16b80 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
16b90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16ba0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
16bb0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
16bc0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
16bd0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
16be0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
16bf0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
16c00 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16c10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16c20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
16c30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16c40 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
16c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
16c60 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
16c70 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
16c80 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
16c90 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
16ca0 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
16cb0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
16cc0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
16cd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
16ce0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
16cf0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
16d00 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
16d10 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
16d20 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
16d30 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
16d40 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
16d50 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16d60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
16d70 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
16d80 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
16d90 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
16da0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
16db0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
16dc0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16de0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16df0 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
16e00 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
16e10 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
16e20 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
16e30 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
16e40 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
16e50 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16e60 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
16e70 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
16e80 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
16e90 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
16ea0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
16eb0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
16ec0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16ed0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16ef0 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
16f00 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
16f10 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
16f20 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
16f30 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
16f40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
16f50 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16f60 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
16f70 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
16f80 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
16f90 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
16fa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16fb0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
16fc0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16fd0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16fe0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16ff0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
17000 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17010 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17020 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
17030 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
17040 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
17050 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
17060 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
17070 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
17080 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
17090 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
170a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
170b0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
170c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
170d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
170e0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
170f0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
17100 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
17110 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
17120 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
17130 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
17140 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
17150 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
17160 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
17170 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
17180 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
17190 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
171a0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
171b0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
171c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
171d0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
171e0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
171f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17200 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
17210 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
17220 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
17230 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
17240 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
17250 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17260 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
17270 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17280 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
17290 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
172a0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
172b0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
172c0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
172d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
172e0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
172f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
17300 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
17310 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
17320 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
17330 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
17340 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
17350 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
17360 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
17370 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17380 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
17390 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
173a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
173b0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
173c0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
173d0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
173e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
173f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17400 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
17410 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
17420 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
17430 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
17440 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
17450 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
17460 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
17470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
17480 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
17490 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
174a0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
174b0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
174c0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
174d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
174e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
174f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17500 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
17510 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
17520 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
17530 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17540 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
17550 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
17560 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
17570 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
17580 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17590 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
175a0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
175b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
175c0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
175d0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
175e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
175f0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
17600 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
17610 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
17620 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
17630 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
17640 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
17650 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
17660 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
17670 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
17680 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
17690 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
176a0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
176b0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
176c0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
176d0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
176e0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
176f0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
17700 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
17710 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
17720 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
17730 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
17740 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
17750 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
17760 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
17770 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
17780 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
17790 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
177a0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
177b0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
177c0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
177d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
177e0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
177f0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
17800 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
17810 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
17820 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
17830 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
17840 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
17850 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
17860 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
17870 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
17880 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
17890 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
178a0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
178b0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
178c0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
178d0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
178e0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
178f0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
17900 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
17910 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
17920 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
17930 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
17940 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
17950 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
17960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17970 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
17980 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
17990 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
179a0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
179b0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
179c0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
179d0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
179e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
179f0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
17a00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
17a10 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
17a20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
17a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17a50 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
17a60 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
17a70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
17a80 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
17a90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17aa0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
17ab0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
17ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17ad0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
17ae0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
17af0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
17b00 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
17b10 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
17b20 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
17b30 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
17b40 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
17b50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17b60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
17b70 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
17b80 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
17b90 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
17ba0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
17bb0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
17bc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17bd0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17be0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17bf0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
17c00 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
17c10 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
17c20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17c30 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
17c40 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
17c50 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
17c60 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
17c70 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
17c80 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
17c90 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
17ca0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
17cb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17cc0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
17cd0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
17ce0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17cf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
17d00 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
17d10 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
17d20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17d30 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17d40 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
17d50 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17d60 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
17d70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
17d80 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
17d90 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
17da0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
17db0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
17dc0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17dd0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17de0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17df0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17e00 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17e20 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17e30 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17e40 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17e50 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17e60 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17e70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17e80 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17e90 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17ea0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
17eb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17ec0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17ed0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17ee0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17ef0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
17f00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
17f10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
17f20 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
17f30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
17f40 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
17f50 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17f60 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17f70 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17f80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
17f90 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
17fa0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17fb0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
17fc0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17fd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17fe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18000 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
18010 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
18020 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
18030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
18040 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
18050 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
18060 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
18070 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
18080 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
18090 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
180a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
180b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
180c0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
180d0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
180e0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
180f0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
18100 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
18110 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
18120 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
18130 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
18140 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
18150 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
18160 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
18170 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
18180 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
18190 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
181a0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
181b0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
181c0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
181d0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
181e0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
181f0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
18200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18220 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
18230 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
18240 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
18250 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
18260 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
18270 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
18280 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
18290 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
182a0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
182b0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
182c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
182d0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
182e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
182f0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
18300 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
18310 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
18320 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
18330 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
18340 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
18350 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
18360 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
18370 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
18380 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
18390 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
183a0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
183b0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
183c0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
183d0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
183e0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
183f0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
18400 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
18410 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
18420 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
18430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
18440 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
18450 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
18460 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
18470 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
18480 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
18490 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
184a0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
184b0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
184c0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
184d0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
184e0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
184f0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
18500 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
18510 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
18520 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
18530 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
18540 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
18550 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
18560 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
18570 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
18580 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
18590 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
185a0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
185b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
185c0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
185d0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
185e0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
185f0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
18600 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
18610 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
18620 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18630 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
18640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
18650 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
18660 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
18670 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
18680 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
18690 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
186a0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
186b0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
186c0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
186d0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
186e0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
186f0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
18700 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
18710 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18720 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
18730 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
18740 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
18750 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
18760 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
18770 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
18780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
18790 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
187a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
187b0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
187c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
187d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
187e0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
187f0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
18800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18810 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
18820 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
18830 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
18840 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
18850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18860 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
18870 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
18880 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
18890 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
188a0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
188b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
188c0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
188d0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
188e0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
188f0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
18900 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
18910 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
18920 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
18930 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
18940 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
18950 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18960 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
18970 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18980 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18990 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
189a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
189b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
189c0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
189d0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
189e0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
189f0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
18a00 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
18a10 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
18a20 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
18a30 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
18a40 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
18a50 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
18a60 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
18a70 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
18a80 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
18a90 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
18aa0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
18ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18ac0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18ad0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18ae0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18af0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18b00 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18b10 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18b20 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18b40 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
18b50 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
18b60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18b70 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18b90 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
18ba0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
18bb0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
18bc0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18bd0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18be0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
18bf0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
18c00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
18c10 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
18c20 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
18c30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18c40 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18c50 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
18c60 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
18c70 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
18c80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18c90 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
18ca0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
18cb0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
18cc0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18ce0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
18cf0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
18d00 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
18d10 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
18d20 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
18d30 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
18d40 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
18d50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18d60 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
18d70 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
18d80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
18d90 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
18da0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
18db0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
18dc0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18dd0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18de0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18df0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18e00 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
18e10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
18e20 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
18e30 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
18e40 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
18e50 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18e60 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
18e70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18e80 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
18e90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
18ea0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
18eb0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
18ec0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18ed0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18ee0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18ef0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
18f00 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
18f10 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
18f20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
18f30 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18f40 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18f50 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18f60 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
18f70 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
18f80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
18f90 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
18fa0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18fb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18fc0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18fe0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18ff0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
19000 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
19010 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
19020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19030 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
19040 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
19050 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
19060 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
19070 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
19080 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
19090 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
190a0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
190b0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
190c0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
190d0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
190e0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
190f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
19110 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
19120 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
19130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19140 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
19150 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
19160 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19170 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19180 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19190 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
191a0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
191b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
191c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
191d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191e0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
191f0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
19200 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19210 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19220 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19230 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
19240 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
19250 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19260 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19270 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19280 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
19290 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
192a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
192b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
192c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
192d0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
192e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
192f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19300 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19310 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19320 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
19330 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19340 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19350 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19360 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
19370 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
19380 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19390 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
193a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
193b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
193c0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
193d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
193e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
193f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19400 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
19410 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
19420 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19430 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19440 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19450 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
19460 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
19470 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19480 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
194a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
194b0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
194c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
194d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
19500 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
19510 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19520 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19540 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
19550 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
19560 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19590 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
195a0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
195b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
195c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
195d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
195e0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
195f0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
19600 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19610 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19630 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
19640 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
19650 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19660 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
19680 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
19690 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
196a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
196b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
196c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
196d0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
196e0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
196f0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
19700 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
19710 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
19720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19730 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
19740 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19750 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19760 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
19770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19780 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
19790 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
197a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
197b0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
197c0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
197d0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
197e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
197f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19800 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19810 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19820 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19830 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
19840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19850 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
19860 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
19870 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
19880 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
198a0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
198b0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
198c0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
198d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198f0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19900 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19910 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19920 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19940 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
19950 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
19960 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19990 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
199a0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
199b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
199c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
199d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199e0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
199f0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19a00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19a10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a30 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
19a40 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
19a50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
19a60 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
19a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a80 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
19a90 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
19aa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
19ab0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
19ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19ad0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
19ae0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
19af0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
19b00 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
19b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19b20 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
19b30 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
19b40 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
19b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
19b60 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
19b70 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
19b80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19b90 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
19ba0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
19bb0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
19bc0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
19bd0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
19be0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
19bf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19c00 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19c10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19c20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19c30 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
19c40 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
19c50 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
19c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
19c70 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
19c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19ca0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
19cb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
19cc0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19cd0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
19ce0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19cf0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19d00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19d10 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
19d20 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
19d30 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19d40 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
19d50 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19d60 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19d70 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19d80 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19d90 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19da0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19db0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19dc0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19dd0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19de0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19df0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19e00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19e10 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19e20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19e30 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
19e40 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19e50 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19e60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19e70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19e80 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19e90 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19ea0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19eb0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19ec0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
19ed0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ee0 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
19ef0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
19f00 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
19f10 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
19f20 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
19f30 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
19f40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
19f50 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
19f60 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
19f70 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
19f80 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
19f90 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
19fa0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
19fb0 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
19fc0 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
19fd0 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
19fe0 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
19ff0 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1a000 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1a010 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1a020 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1a030 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1a040 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1a050 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1a060 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1a070 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1a080 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1a090 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1a0a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1a0b0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1a0c0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1a0d0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1a0e0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1a0f0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1a100 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1a110 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1a120 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a130 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1a140 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1a150 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1a160 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a170 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1a180 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1a190 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1a1a0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1a1b0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1a1c0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1a1d0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1a1e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1a1f0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1a200 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1a210 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a220 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1a230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a240 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1a250 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1a260 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1a270 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1a280 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1a290 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1a2a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1a2b0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1a2c0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1a2d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1a2e0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1a2f0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1a300 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1a310 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1a320 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1a330 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1a340 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1a350 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1a360 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1a370 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1a380 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1a390 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1a3a0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1a3b0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1a3c0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1a3d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a3e0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1a3f0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1a400 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1a410 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1a420 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1a430 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1a440 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1a450 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1a460 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a470 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1a480 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1a490 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1a4a0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1a4b0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1a4c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a4d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1a4e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1a4f0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1a500 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1a510 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1a520 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1a530 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1a540 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1a550 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a560 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a570 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1a580 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1a590 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1a5a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1a5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a5c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1a5d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1a5e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1a5f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a600 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1a610 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1a620 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1a630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a640 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1a650 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1a660 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1a670 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1a680 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a690 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a6a0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1a6b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1a6c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1a6d0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1a6e0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1a6f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1a700 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1a710 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1a720 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
1a730 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
1a740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1a750 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1a760 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1a770 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1a780 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1a790 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a7a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1a7b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1a7c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1a7d0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1a7e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1a7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a800 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1a810 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1a820 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1a830 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1a840 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1a850 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1a860 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1a870 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1a880 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1a890 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1a8a0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1a8b0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1a8c0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1a8d0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1a8e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1a8f0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1a900 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1a910 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a920 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1a930 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1a940 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1a950 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1a960 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1a970 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1a980 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1a990 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1a9a0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1a9b0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1a9c0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1a9d0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1a9e0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1a9f0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1aa00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1aa10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1aa20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1aa30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1aa40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1aa50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1aa60 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1aa70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1aa80 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1aa90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1aaa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1aab0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1aac0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1aad0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1aae0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1aaf0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1ab00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1ab10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1ab20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1ab30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1ab40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1ab50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1ab60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ab70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1ab80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1ab90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1aba0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1abb0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1abc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1abd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1abe0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1abf0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1ac00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1ac10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1ac20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1ac30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1ac40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1ac50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1ac60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ac70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1ac80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1ac90 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1aca0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1acb0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1acc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1acd0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1ace0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1acf0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1ad00 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1ad10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1ad20 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1ad30 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1ad40 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
1ad50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1ad60 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
1ad70 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1ad80 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1ad90 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1ada0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1adb0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1adc0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1add0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1ade0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1adf0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1ae00 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1ae10 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1ae20 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1ae30 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ae40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ae50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ae60 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1ae70 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1ae80 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1ae90 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1aea0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1aeb0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1aec0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1aed0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1aee0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1aef0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1af00 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1af10 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1af20 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1af30 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1af40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1af50 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1af60 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1af70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1af80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1af90 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1afa0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1afb0 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1afc0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1afd0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1afe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1aff0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1b000 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1b010 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1b020 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1b030 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1b040 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1b050 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b060 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1b070 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1b080 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1b090 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1b0a0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1b0b0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1b0c0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1b0d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1b0e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1b0f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1b100 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1b110 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1b120 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1b130 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b140 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1b150 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1b160 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1b170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1b180 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b190 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1b1a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1b1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b1c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1b1d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1b1e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1b1f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1b200 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1b210 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1b220 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1b230 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1b240 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1b250 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1b260 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1b270 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1b280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1b290 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1b2a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1b2b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1b2c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1b2d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1b2e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1b2f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1b300 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1b310 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1b320 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1b330 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1b340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b350 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1b360 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1b370 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1b380 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1b390 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1b3a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1b3b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1b3c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1b3d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1b3e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1b3f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1b400 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1b410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b420 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1b430 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1b440 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1b450 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1b460 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1b470 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b480 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1b490 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1b4a0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1b4b0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1b4c0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1b4d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1b4e0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1b4f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1b500 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1b510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b520 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1b530 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1b540 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1b550 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1b560 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1b570 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1b580 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1b590 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1b5a0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1b5b0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1b5c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1b5d0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1b5e0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1b5f0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1b600 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1b610 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1b620 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1b630 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1b640 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1b650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1b660 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1b670 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1b680 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1b690 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1b6a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b6b0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1b6c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1b6d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1b6e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1b6f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1b700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b710 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1b720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1b730 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1b740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b750 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1b760 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1b770 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1b780 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1b790 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1b7a0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1b7b0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1b7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1b7d0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1b7e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b7f0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1b800 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1b810 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b820 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1b830 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1b840 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1b850 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1b860 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1b870 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1b880 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1b890 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1b8a0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1b8b0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1b8c0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1b8d0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1b8e0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1b8f0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1b900 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1b910 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1b920 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1b930 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1b940 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1b950 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1b960 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1b970 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b990 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1b9a0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1b9b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1b9c0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1b9d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1b9e0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1b9f0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1ba00 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1ba10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1ba20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1ba30 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ba40 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ba50 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1ba60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1ba70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1ba80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1ba90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1baa0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1bab0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1bac0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1bad0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1bae0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1baf0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1bb00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1bb10 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1bb20 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1bb30 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1bb40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1bb50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1bb60 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1bb70 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1bb80 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1bb90 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1bba0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1bbb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1bbc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1bbd0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1bbe0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1bbf0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bc00 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1bc10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1bc20 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1bc30 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1bc40 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1bc50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bc60 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1bc70 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1bc80 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1bc90 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1bca0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1bcb0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1bcc0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1bcd0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1bce0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1bcf0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1bd00 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1bd10 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1bd20 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1bd30 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1bd40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bd50 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1bd60 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1bd70 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1bd80 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1bda0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1bdb0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1bdc0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1bdd0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1bde0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1bdf0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1be00 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1be10 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1be20 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1be30 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1be40 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1be50 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1be60 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1be70 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1be80 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1be90 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1bea0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1beb0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1bec0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1bed0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1bee0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1bef0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bf00 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1bf10 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1bf20 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1bf30 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1bf40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1bf50 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1bf60 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1bf70 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1bf80 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1bf90 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1bfa0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1bfb0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1bfc0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1bfd0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1bfe0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1bff0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1c000 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1c010 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1c020 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1c030 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1c040 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1c050 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c060 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1c070 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1c080 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1c090 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1c0a0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1c0b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1c0c0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1c0d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1c0e0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1c0f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1c100 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1c110 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1c120 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1c130 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1c140 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1c150 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1c160 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1c170 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1c180 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1c190 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1c1a0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1c1b0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1c1c0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1c1d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1c1e0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1c1f0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1c200 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1c210 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1c220 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1c230 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1c240 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1c250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1c260 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1c270 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1c280 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1c290 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1c2a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1c2b0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1c2c0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1c2d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1c2e0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1c2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1c300 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1c310 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1c320 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1c330 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1c340 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1c350 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1c360 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1c370 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1c380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c390 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1c3a0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1c3b0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1c3c0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1c3d0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1c3e0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1c3f0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1c400 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1c410 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1c420 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1c430 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1c440 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1c450 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1c460 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1c470 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1c480 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1c490 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1c4a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1c4b0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1c4c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1c4d0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c4e0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1c4f0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1c500 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1c510 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1c520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c530 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1c540 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1c550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1c560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1c570 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1c580 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1c590 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1c5a0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1c5b0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1c5c0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1c5d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1c5e0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1c5f0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1c600 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1c610 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1c620 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1c630 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1c640 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1c650 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1c660 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1c670 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1c680 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1c690 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1c6a0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1c6b0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1c6c0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1c6d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1c6e0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1c6f0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1c700 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1c710 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c720 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1c730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c740 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1c750 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1c760 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1c770 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c780 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1c790 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1c7a0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1c7b0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1c7c0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1c7d0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1c7e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1c7f0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1c800 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1c810 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
1c820 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1c830 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1c840 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1c850 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1c860 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
1c870 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
1c880 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
1c890 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
1c8a0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1c8b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1c8c0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
1c8d0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
1c8e0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1c8f0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
1c900 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1c910 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
1c920 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1c930 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1c940 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1c950 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
1c960 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1c970 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1c980 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1c990 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1c9a0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1c9b0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
1c9c0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
1c9d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1c9e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
1c9f0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
1ca00 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1ca10 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
1ca20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ca30 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
1ca40 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
1ca50 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
1ca60 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1ca70 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
1ca80 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
1ca90 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
1caa0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
1cab0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
1cac0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
1cad0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
1cae0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
1caf0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
1cb00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1cb10 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
1cb20 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
1cb30 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
1cb40 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
1cb50 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
1cb60 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
1cb70 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
1cb80 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
1cb90 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
1cba0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
1cbb0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
1cbc0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1cbd0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1cbe0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1cbf0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1cc00 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1cc10 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1cc20 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1cc30 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1cc40 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1cc50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1cc60 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1cc70 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1cc80 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1cc90 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1cca0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ccb0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1ccc0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1ccd0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1cce0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1ccf0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1cd00 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1cd10 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1cd20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1cd30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1cd40 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1cd50 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1cd60 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1cd70 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1cd80 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1cd90 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1cda0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1cdb0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1cdc0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1cdd0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1cde0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1cdf0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1ce00 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1ce10 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1ce20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1ce30 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
1ce40 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1ce50 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1ce60 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1ce70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1ce80 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1ce90 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
1cea0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1ceb0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
1cec0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
1ced0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
1cee0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
1cef0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
1cf00 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
1cf10 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
1cf20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1cf30 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1cf40 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
1cf50 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1cf60 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
1cf70 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
1cf80 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
1cf90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
1cfa0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
1cfb0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
1cfc0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
1cfd0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cfe0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1cff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d000 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1d010 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1d020 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
1d030 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
1d040 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d050 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1d060 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d070 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1d080 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1d090 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1d0a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d0b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d0c0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1d0d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d0e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d0f0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1d100 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1d110 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1d120 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1d130 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1d140 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1d150 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1d160 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1d170 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1d180 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1d190 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d1a0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1d1b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d1c0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1d1d0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1d1e0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1d1f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d200 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d210 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d220 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1d230 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d240 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1d250 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1d260 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1d270 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d280 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1d290 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1d2a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d2b0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1d2c0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1d2d0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1d2e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d2f0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1d300 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
1d310 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
1d320 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
1d330 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
1d340 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
1d350 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
1d360 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
1d370 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d380 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1d390 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1d3a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d3b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1d3c0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1d3d0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1d3e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d3f0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1d400 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d410 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1d420 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1d430 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1d440 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1d450 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d460 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d470 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d480 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1d490 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1d4a0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1d4b0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1d4c0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1d4d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d4e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d4f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d500 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1d510 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
1d520 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
1d530 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
1d540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
1d550 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d560 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1d570 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1d580 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d590 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1d5a0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1d5b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1d5c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1d5d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1d5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d5f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1d600 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1d610 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1d620 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1d630 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d640 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1d650 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1d660 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1d670 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1d680 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1d690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1d6a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1d6b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1d6c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1d6d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1d6e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1d6f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1d700 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1d710 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1d720 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d730 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1d740 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1d750 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d760 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d770 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1d780 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d790 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d7a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1d7b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d7c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1d7d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1d7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d7f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1d800 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1d810 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1d820 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1d830 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1d840 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1d850 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1d860 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1d870 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1d880 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1d890 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1d8a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1d8b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1d8c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1d8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1d8e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1d8f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1d900 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1d910 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1d920 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1d930 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1d940 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1d950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d960 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1d970 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1d980 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1d990 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1d9a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1d9b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1d9c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1d9d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1d9e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1d9f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1da00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1da10 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1da20 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1da30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1da40 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1da50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1da60 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1da70 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1da80 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1da90 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1daa0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1dab0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1dac0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1dad0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1dae0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1daf0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1db00 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1db10 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1db20 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1db30 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1db40 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1db50 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1db60 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1db70 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1db80 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1db90 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1dba0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1dbb0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1dbc0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1dbd0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1dbe0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1dbf0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1dc00 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1dc10 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1dc20 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1dc30 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1dc40 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1dc50 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1dc60 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1dc70 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1dc80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1dc90 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1dca0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1dcb0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1dcc0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1dcd0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1dce0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1dcf0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1dd00 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1dd10 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1dd20 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1dd30 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1dd40 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1dd50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1dd60 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1dd70 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1dd80 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1dd90 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1dda0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1ddb0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1ddc0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1ddd0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1dde0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1ddf0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1de00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1de10 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1de20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1de30 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1de40 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1de50 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1de60 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1de70 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1de80 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1de90 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1dea0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1deb0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1dec0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1ded0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1dee0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1def0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1df00 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1df10 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1df20 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1df30 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1df40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1df50 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1df60 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1df70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1df80 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1df90 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1dfa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1dfb0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1dfc0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1dfd0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1dfe0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1dff0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1e000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1e010 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1e020 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e030 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1e040 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1e050 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1e060 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1e070 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1e080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1e090 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1e0a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1e0b0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1e0c0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1e0d0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1e0e0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1e0f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1e100 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1e110 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1e120 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1e130 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1e140 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1e150 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1e160 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1e170 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e180 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1e190 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1e1a0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1e1b0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1e1c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1e1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1e1e0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1e1f0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1e200 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1e210 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1e220 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1e230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1e240 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1e250 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1e260 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1e270 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1e280 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
1e290 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1e2a0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1e2b0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1e2c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1e2d0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1e2e0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1e2f0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1e300 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1e310 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1e320 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1e330 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1e340 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1e350 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1e360 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1e370 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1e380 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1e390 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1e3a0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1e3b0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1e3c0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1e3d0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1e3e0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1e3f0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1e400 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1e410 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1e420 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1e430 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1e440 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1e450 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1e460 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1e470 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1e480 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
1e490 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
1e4a0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1e4b0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1e4c0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
1e4d0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
1e4e0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
1e4f0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
1e500 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
1e510 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1e520 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
1e530 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1e540 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
1e550 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
1e560 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
1e570 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
1e580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1e590 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1e5a0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
1e5b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1e5c0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
1e5d0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
1e5e0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
1e5f0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
1e600 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
1e610 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
1e620 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
1e630 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
1e640 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
1e650 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
1e660 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
1e670 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
1e680 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
1e690 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
1e6a0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
1e6b0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
1e6c0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
1e6d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
1e6e0 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT2] compile-ti
1e6f0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
1e700 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
1e710 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1e720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1e730 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1e740 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e750 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e760 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e770 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e780 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e790 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1e7a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e7b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e7c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e7d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e7e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e7f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e800 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e810 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e820 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1e830 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e840 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e850 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e860 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1e880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e890 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e8a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e8b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e8c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e8d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1e8e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e8f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e900 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e910 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e920 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e930 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e940 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e950 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e960 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e970 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e980 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e990 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e9a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1e9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e9c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1e9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1e9e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1e9f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1ea00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1ea10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ea20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1ea30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ea40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ea50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ea60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ea70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ea80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1ea90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1eaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1eab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1eac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1ead0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1eae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1eaf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1eb00 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1eb10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1eb20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1eb30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1eb40 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1eb50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1eb60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1eb70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1eb80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1eb90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1eba0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ebb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1ebc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1ebd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1ebe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ebf0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1ec00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1ec10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1ec20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1ec30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1ec40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1ec50 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1ec60 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
1ec70 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1ec80 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1ec90 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1eca0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1ecb0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1ecc0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1ecd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ece0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1ecf0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1ed00 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1ed10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1ed30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ed40 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
1ed50 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1ed60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1ed70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1ed80 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1ed90 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1eda0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
1edb0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
1edc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
1edd0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
1ede0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1edf0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
1ee00 66 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61 72  f.** the [prepar
1ee10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
1ee20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  is guaranteed to
1ee30 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
1ee40 61 73 65 20 66 69 6c 65 0a 2a 2a 20 75 6e 6d 6f  ase file.** unmo
1ee50 64 69 66 69 65 64 2e 20 20 5e 49 66 20 74 68 65  dified.  ^If the
1ee60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
1ee70 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
1ee80 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
1ee90 65 20 28 7a 65 72 6f 29 0a 2a 2a 20 74 68 65 6e  e (zero).** then
1eea0 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
1eeb0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1eec0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
1eed0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 74 68  ase file, but th
1eee0 69 73 0a 2a 2a 20 69 73 20 6e 6f 74 20 67 75 61  is.** is not gua
1eef0 72 61 6e 74 65 65 64 20 61 73 20 74 68 65 20 77  ranteed as the w
1ef00 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d  rite operation m
1ef10 69 67 68 74 20 62 65 20 63 6f 6e 64 69 74 69 6f  ight be conditio
1ef20 6e 61 6c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  nal and the.** c
1ef30 6f 6e 64 69 74 69 6f 6e 20 6d 69 67 68 74 20 6e  ondition might n
1ef40 6f 74 20 62 65 20 6d 65 74 2e 20 20 5e 49 66 20  ot be met.  ^If 
1ef50 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1ef60 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1ef70 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
1ef80 79 28 58 29 20 72 65 74 75 72 6e 73 20 74 72 75  y(X) returns tru
1ef90 65 2e 20 20 49 66 20 58 20 69 73 20 61 20 6e 6f  e.  If X is a no
1efa0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 62  n-NULL pointer b
1efb0 75 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 70  ut.** is not a p
1efc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
1efd0 64 2c 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  d, unfinalized p
1efe0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1eff0 74 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 62  t, then the.** b
1f000 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1f010 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
1f020 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2f 0a 69 6e  y harmful..*/.in
1f030 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
1f040 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
1f050 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1f070 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
1f080 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
1f090 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
1f0a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f0b0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
1f0c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1f0d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1f0e0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
1f0f0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
1f100 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
1f110 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
1f120 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
1f130 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
1f140 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
1f150 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
1f160 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
1f170 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
1f180 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
1f190 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
1f1a0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
1f1b0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
1f1c0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
1f1d0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
1f1e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
1f1f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1f200 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
1f210 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
1f220 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
1f230 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
1f240 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
1f250 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f260 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
1f270 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
1f280 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
1f290 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
1f2a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1f2b0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
1f2c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1f2d0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
1f2e0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
1f2f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1f300 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
1f310 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
1f320 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f330 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
1f340 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
1f350 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
1f360 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
1f370 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
1f380 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
1f390 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
1f3a0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
1f3b0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1f3c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1f3d0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
1f3e0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
1f3f0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1f400 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
1f410 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1f420 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
1f430 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
1f440 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
1f450 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
1f460 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
1f470 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
1f480 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
1f490 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
1f4a0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
1f4b0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
1f4c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
1f4d0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
1f4e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1f4f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
1f500 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
1f510 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
1f520 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1f530 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1f540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1f550 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
1f560 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
1f570 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
1f580 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
1f590 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
1f5a0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
1f5b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1f5c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
1f5d0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
1f5e0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1f5f0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
1f600 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
1f610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1f620 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
1f630 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
1f640 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
1f650 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1f660 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
1f670 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
1f680 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
1f690 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1f6a0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
1f6b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1f6c0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
1f6d0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
1f6e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1f6f0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
1f700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1f710 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
1f720 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
1f730 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
1f740 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f750 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
1f760 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
1f770 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
1f780 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f790 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
1f7a0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1f7b0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
1f7c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
1f7d0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
1f7e0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1f7f0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
1f800 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1f810 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
1f820 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
1f830 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
1f840 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
1f850 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
1f860 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
1f870 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
1f880 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
1f890 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
1f8a0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
1f8b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
1f8c0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
1f8d0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
1f8e0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
1f8f0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
1f900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
1f910 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1f920 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1f930 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
1f940 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1f950 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
1f960 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
1f970 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
1f980 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
1f990 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1f9a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
1f9b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
1f9c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
1f9d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
1f9e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
1f9f0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
1fa00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
1fa10 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
1fa20 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
1fa30 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
1fa40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fa50 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
1fa60 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1fa70 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
1fa80 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
1fa90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
1faa0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
1fab0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1fac0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
1fad0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1fae0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1faf0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
1fb00 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
1fb10 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
1fb20 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
1fb30 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
1fb40 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
1fb50 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
1fb60 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
1fb70 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1fb80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1fb90 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
1fba0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
1fbb0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
1fbc0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
1fbd0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
1fbe0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
1fbf0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
1fc00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1fc10 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1fc20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1fc30 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1fc40 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1fc50 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
1fc60 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
1fc70 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
1fc80 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
1fc90 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
1fca0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
1fcb0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
1fcc0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
1fcd0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
1fce0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
1fcf0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
1fd00 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
1fd10 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
1fd20 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
1fd30 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1fd40 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1fd50 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
1fd60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1fd70 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1fd80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fd90 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
1fda0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
1fdb0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1fdc0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1fdd0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
1fde0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1fdf0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
1fe00 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
1fe10 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1fe20 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1fe30 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1fe40 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1fe50 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
1fe60 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
1fe70 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1fe80 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
1fe90 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
1fea0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
1feb0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
1fec0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
1fed0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
1fee0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
1fef0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
1ff00 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
1ff10 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
1ff20 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1ff30 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1ff40 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1ff50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1ff60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ff70 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
1ff80 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
1ff90 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
1ffa0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
1ffb0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
1ffc0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
1ffd0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
1ffe0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
1fff0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20000 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
20010 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
20020 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
20030 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
20040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
20050 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
20060 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
20070 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
20080 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
20090 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
200a0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
200b0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
200c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
200d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
200e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
200f0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
20100 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
20110 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
20120 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
20130 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
20140 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
20150 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
20160 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
20170 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
20180 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
20190 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
201a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
201b0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
201c0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
201d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
201e0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
201f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20200 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
20210 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
20220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20230 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
20240 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
20250 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20260 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
20270 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
20280 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
20290 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
202a0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
202b0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
202c0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
202d0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
202e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
202f0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
20300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
20310 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
20320 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
20330 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
20340 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
20350 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
20360 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
20370 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
20380 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
20390 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
203a0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
203b0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
203c0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
203d0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
203e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
203f0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
20400 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
20410 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
20420 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
20430 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
20440 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
20450 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
20460 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
20470 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
20480 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
20490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
204a0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
204b0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
204c0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
204d0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
204e0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
204f0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
20500 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
20510 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
20520 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
20530 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
20540 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
20550 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
20560 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
20570 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
20580 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
20590 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
205a0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
205b0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
205c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
205d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
205e0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
205f0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
20600 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
20610 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
20620 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
20630 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
20640 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
20650 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
20660 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
20670 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
20680 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
20690 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
206a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
206b0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
206c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
206d0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
206e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
206f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
20700 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
20710 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20720 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
20730 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
20740 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
20750 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
20760 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
20770 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
20780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20790 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
207a0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
207b0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
207c0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
207d0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
207e0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
207f0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
20800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
20810 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
20820 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
20830 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
20840 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
20850 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20860 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
20870 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
20880 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
20890 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
208a0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
208b0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
208c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
208d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
208e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
208f0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
20900 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
20910 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
20920 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
20930 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
20940 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20950 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20960 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
20970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
20980 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
20990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
209a0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
209b0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
209c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
209d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
209e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
209f0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
20a00 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
20a10 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
20a20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20a30 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
20a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
20a50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20a60 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
20a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
20a80 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
20a90 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
20aa0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
20ab0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
20ac0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
20ad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20ae0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
20af0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
20b00 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
20b10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
20b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20b30 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
20b40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
20b50 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
20b60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
20b70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20b80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
20b90 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
20bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20bc0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
20bd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
20be0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
20bf0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
20c00 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
20c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
20c20 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
20c30 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
20c40 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
20c50 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
20c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20c70 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
20c80 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
20c90 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
20ca0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
20cb0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
20cc0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
20cd0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
20ce0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
20cf0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
20d00 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
20d10 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
20d20 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
20d30 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
20d40 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
20d50 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
20d60 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
20d70 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
20d80 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
20d90 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
20da0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
20db0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
20dc0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
20dd0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
20de0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
20df0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
20e00 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
20e10 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
20e20 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
20e30 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
20e40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20e50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20e60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20e70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20e80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
20e90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
20ea0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20eb0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
20ec0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
20ed0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
20ee0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
20ef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
20f00 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
20f10 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
20f20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20f30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
20f40 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
20f50 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
20f60 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
20f70 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
20f80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
20f90 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
20fa0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
20fb0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
20fc0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
20fd0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
20fe0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
20ff0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
21000 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
21010 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
21020 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
21030 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
21040 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
21050 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
21060 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
21070 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
21080 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
21090 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
210a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
210b0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
210c0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
210d0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
210e0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
210f0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
21100 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
21110 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
21120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21130 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
21140 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
21150 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
21160 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
21170 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
21180 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
21190 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
211a0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
211b0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
211c0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
211d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
211e0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
211f0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
21200 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
21210 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
21220 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
21230 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
21240 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21250 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21260 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
21270 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21280 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21290 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
212a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
212b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
212c0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
212d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
212e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
212f0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
21300 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
21310 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
21320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21340 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
21350 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
21360 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
21370 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
21380 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
21390 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
213a0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
213b0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
213c0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
213d0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
213e0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
213f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
21400 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21410 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
21420 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
21430 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
21440 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
21450 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
21460 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
21470 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
21480 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
21490 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
214a0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
214b0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
214c0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
214d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
214e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
214f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
21500 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
21510 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
21520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21530 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
21540 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
21550 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21560 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
21570 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21580 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
21590 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
215a0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
215b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
215c0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
215d0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
215e0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
215f0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
21600 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
21610 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
21620 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
21630 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
21640 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
21650 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
21660 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21670 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
21680 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
21690 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
216a0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
216b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
216c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
216d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
216e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
216f0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
21700 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
21710 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
21720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
21730 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
21740 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
21750 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
21760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21770 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
21780 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
21790 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
217a0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
217b0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
217c0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
217d0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
217e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
217f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
21800 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
21810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
21820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
21830 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
21840 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
21850 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
21860 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
21870 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
21880 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
21890 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
218a0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
218b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
218c0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
218d0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
218e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
218f0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
21900 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
21910 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
21920 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
21930 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
21940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
21950 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
21960 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
21970 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
21980 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
21990 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
219a0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
219b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
219c0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
219d0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
219e0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
219f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21a00 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
21a10 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
21a20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
21a30 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
21a40 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
21a50 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
21a60 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
21a70 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
21a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
21a90 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
21aa0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
21ab0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
21ac0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
21ad0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
21ae0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
21af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
21b00 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
21b10 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
21b20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
21b30 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
21b40 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
21b50 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
21b60 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
21b70 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
21b80 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
21b90 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
21ba0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
21bb0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
21bc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
21bd0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
21be0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
21bf0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
21c00 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
21c10 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
21c20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
21c30 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
21c40 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
21c50 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
21c60 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
21c70 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
21c80 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
21c90 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
21ca0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
21cb0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
21cc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21cd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21ce0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
21cf0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21d00 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
21d10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21d20 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
21d30 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
21d40 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
21d50 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
21d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
21d70 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
21d80 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
21d90 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
21da0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
21db0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
21dc0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
21dd0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
21de0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
21df0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
21e00 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
21e10 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
21e20 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
21e30 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
21e40 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
21e50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
21e60 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
21e70 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
21e80 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
21e90 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
21ea0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
21eb0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
21ec0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
21ed0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
21ee0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
21ef0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
21f00 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
21f10 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
21f20 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
21f30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
21f40 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
21f50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
21f60 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
21f70 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
21f80 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
21f90 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
21fa0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
21fb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
21fc0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
21fd0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
21fe0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
21ff0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
22000 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
22010 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
22020 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22030 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
22040 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
22050 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22060 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
22070 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
22080 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
22090 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
220a0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
220b0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
220c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
220d0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
220e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
220f0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
22100 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
22110 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
22120 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
22130 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
22140 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
22150 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
22160 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
22170 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
22180 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
22190 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
221a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
221b0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
221c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
221d0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
221e0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
221f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
22200 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
22210 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
22220 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
22230 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
22240 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
22250 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
22260 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
22270 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
22280 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
22290 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
222a0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
222b0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
222c0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
222d0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
222e0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
222f0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
22300 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
22310 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
22320 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
22330 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
22340 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
22350 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
22360 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
22370 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
22380 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
22390 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
223a0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
223b0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
223c0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
223d0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
223e0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
223f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22400 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
22410 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
22420 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
22430 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
22440 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
22450 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
22460 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
22470 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
22480 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
22490 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
224a0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
224b0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
224c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
224d0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
224e0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
224f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
22500 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22510 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
22520 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22530 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
22540 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
22550 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
22560 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22570 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
22580 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
22590 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
225a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
225b0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
225c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
225d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
225e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
225f0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
22600 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22610 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22620 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
22630 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
22640 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
22650 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22660 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
22670 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22680 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
22690 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
226a0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
226b0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
226c0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
226d0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
226e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
226f0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
22700 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
22710 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
22720 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
22730 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
22740 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
22750 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
22760 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
22770 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
22780 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
22790 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
227a0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
227b0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
227c0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
227d0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
227e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
227f0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
22800 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
22810 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
22820 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
22830 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
22840 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
22850 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
22860 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
22870 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
22880 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
22890 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
228a0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
228b0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
228c0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
228d0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
228e0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
228f0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
22900 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
22910 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
22920 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
22930 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
22940 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
22950 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
22960 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
22970 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
22980 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
22990 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
229a0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
229b0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
229c0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
229d0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
229e0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
229f0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
22a00 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
22a10 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
22a20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
22a30 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
22a40 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
22a50 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
22a60 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
22a70 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
22a80 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
22a90 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
22aa0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
22ab0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
22ac0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
22ad0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
22ae0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
22af0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
22b00 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
22b10 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
22b20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22b30 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
22b40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22b50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
22b60 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
22b70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
22b80 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
22b90 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
22ba0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
22bb0 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
22bc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22bd0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
22be0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
22bf0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
22c00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22c10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22c20 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
22c30 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
22c40 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
22c50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22c60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
22c70 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
22c80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
22c90 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
22ca0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
22cb0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
22cc0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
22cd0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
22ce0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
22cf0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
22d00 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
22d10 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
22d20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
22d30 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
22d40 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
22d50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
22d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22d70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
22d80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22d90 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
22da0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
22db0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
22dc0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
22dd0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
22de0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
22df0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
22e00 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
22e10 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
22e20 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
22e30 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
22e40 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
22e50 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
22e60 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
22e70 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
22e80 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
22e90 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
22ea0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
22eb0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
22ec0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
22ed0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
22ee0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
22ef0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
22f00 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
22f10 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
22f20 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
22f30 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
22f40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
22f50 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
22f60 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
22f70 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
22f80 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
22f90 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
22fa0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
22fb0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
22fc0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
22fd0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
22fe0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
22ff0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
23000 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
23010 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
23020 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
23030 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
23040 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
23050 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
23060 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
23070 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
23080 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
23090 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
230a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
230b0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
230c0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
230d0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
230e0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
230f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
23100 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
23110 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
23120 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
23130 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
23140 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
23150 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
23160 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
23170 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
23180 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
23190 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
231a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
231b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
231c0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
231d0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
231e0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
231f0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
23200 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
23210 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
23220 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
23230 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
23240 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
23250 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
23260 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
23270 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
23280 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
23290 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
232a0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
232b0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
232c0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
232d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
232e0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
232f0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
23300 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
23310 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
23320 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
23330 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
23340 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
23350 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
23360 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
23370 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
23380 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
23390 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
233a0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
233b0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
233c0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
233d0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
233e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
233f0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
23400 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
23410 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
23420 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
23430 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
23440 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
23450 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
23460 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
23470 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
23480 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
23490 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
234a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
234b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
234c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
234d0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
234e0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
234f0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
23500 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
23510 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
23520 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
23530 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
23540 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
23550 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
23560 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
23570 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
23580 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
23590 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
235a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
235b0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
235c0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
235d0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
235e0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
235f0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
23600 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
23610 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
23620 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
23630 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
23640 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
23650 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
23660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23670 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
23680 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
23690 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
236a0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
236b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
236c0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
236d0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
236e0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
236f0 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69  .1, it was requi
23700 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c  red.** after sql
23710 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
23720 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74  rned anything ot
23730 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
23740 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73  _ROW] that.** [s
23750 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23760 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
23770 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
23780 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
23790 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
237a0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76    Failure to inv
237b0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  oke [sqlite3_res
237c0 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61  et()] in this wa
237d0 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c  y would.** resul
237e0 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
237f0 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
23800 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70  rom sqlite3_step
23810 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a  ().  But after.*
23820 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  * version 3.6.23
23830 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
23840 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67  () began calling
23850 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23860 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  )] .** automatic
23870 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
23880 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
23890 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
238a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
238b0 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66    .**.** <b>Goof
238c0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
238d0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
238e0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
238f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
23900 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
23910 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
23920 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
23930 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
23940 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
23950 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
23960 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
23970 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
23980 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
23990 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
239a0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
239b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
239c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
239d0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
239e0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
239f0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
23a00 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
23a10 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
23a20 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
23a30 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
23a40 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
23a50 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
23a60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
23a70 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
23a80 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
23a90 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
23aa0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
23ab0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
23ac0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
23ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23ae0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
23af0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
23b00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23b10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23b20 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
23b30 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
23b40 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
23b50 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
23b60 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
23b70 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
23b80 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
23b90 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
23ba0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
23bb0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
23bc0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
23bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
23be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23bf0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
23c00 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
23c10 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
23c20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
23c30 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
23c40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
23c50 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
23c60 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
23c70 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
23c80 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
23c90 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
23ca0 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
23cb0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
23cc0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
23cd0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
23ce0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
23cf0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
23d00 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
23d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
23d20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
23d30 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
23d40 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
23d50 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
23d60 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
23d70 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
23d80 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
23d90 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
23da0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ter..**.** See a
23db0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
23dc0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
23dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
23de0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
23df0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
23e10 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
23e20 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
23e30 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
23e40 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
23e50 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
23e60 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
23e70 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
23e80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23e90 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
23ea0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
23eb0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
23ec0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
23ed0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
23ee0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
23ef0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
23f00 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
23f10 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
23f20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
23f30 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
23f40 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
23f50 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
23f60 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
23f70 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
23f80 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
23f90 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
23fa0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
23fb0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
23fc0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
23fd0 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
23fe0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
23ff0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
24000 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
24010 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
24020 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
24030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
24040 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
24050 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
24060 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24070 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
24080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
24090 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
240a0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
240b0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
240c0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
240d0 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
240e0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
240f0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
24100 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
24110 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
24120 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
24130 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
24140 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
24150 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
24160 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
24170 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
24180 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
24190 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
241a0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
241b0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
241c0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
241d0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
241e0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
241f0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
24200 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
24210 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
24220 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
24230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24240 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
24250 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
24260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
24270 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
24280 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
24290 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
242a0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
242b0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
242c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
242d0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
242e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
242f0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
24300 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
24310 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
24320 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
24330 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24340 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
24350 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
24360 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
24370 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
24380 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
24390 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
243a0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
243b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
243c0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
243d0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
243e0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
243f0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
24400 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
24410 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
24420 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
24430 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
24440 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
24450 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
24460 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
24470 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
24480 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
24490 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
244a0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
244b0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
244c0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
244d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
244e0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
244f0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
24500 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
24510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
24520 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
24530 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24540 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
24550 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
24560 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
24570 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
24580 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
24590 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
245a0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
245b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
245c0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
245d0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
245e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
245f0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
24600 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
24610 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
24620 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
24630 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
24640 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
24650 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
24660 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
24670 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24680 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
24690 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
246a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
246b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
246c0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
246d0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
246e0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
246f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
24700 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
24710 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
24720 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
24730 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
24740 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
24750 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
24760 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
24770 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
24780 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
24790 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
247a0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
247b0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
247c0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
247d0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
247e0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
247f0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
24800 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24810 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
24820 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
24830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
24840 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
24850 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
24860 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
24870 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
24880 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
24890 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
248a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
248b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
248c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
248d0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
248e0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
248f0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
24900 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
24910 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
24920 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
24930 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
24940 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
24950 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
24960 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
24970 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
24980 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
24990 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
249a0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
249b0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
249c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
249d0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
249e0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
249f0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
24a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24a10 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
24a20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
24a30 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
24a40 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
24a50 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
24a60 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
24a70 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
24a80 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
24a90 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
24aa0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
24ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24ac0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
24ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
24ae0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
24af0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
24b00 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
24b10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24b20 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
24b30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
24b40 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
24b50 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
24b60 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
24b70 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
24b80 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
24b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24ba0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
24bb0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
24bc0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
24bd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
24be0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
24bf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
24c00 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
24c10 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
24c20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
24c30 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
24c40 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
24c50 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
24c60 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
24c70 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
24c80 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
24c90 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
24ca0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
24cb0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
24cc0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
24cd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24ce0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
24cf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
24d00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
24d10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24d20 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
24d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24d40 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
24d50 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
24d60 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
24d70 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
24d80 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
24d90 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
24da0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
24db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
24dc0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
24dd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24de0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
24df0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
24e00 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
24e10 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
24e20 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
24e30 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
24e40 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
24e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24e60 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
24e70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24e80 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
24e90 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
24ea0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
24eb0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
24ec0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
24ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24ee0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
24ef0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
24f00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
24f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
24f20 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
24f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24f40 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
24f50 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
24f60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
24f70 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
24f80 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24f90 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
24fa0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
24fb0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
24fc0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
24fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
24fe0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
24ff0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
25000 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
25010 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
25020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
25030 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
25040 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
25050 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
25060 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
25070 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
25080 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
25090 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
250a0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
250b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
250c0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
250d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
250e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
250f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
25100 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
25110 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
25120 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
25130 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
25140 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
25150 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
25160 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
25170 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
25180 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
25190 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
251a0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
251b0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
251c0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
251d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
251e0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
251f0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
25200 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
25210 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
25220 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
25230 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
25240 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
25250 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
25260 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
25270 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
25280 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
25290 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
252a0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
252b0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
252c0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
252d0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
252e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
252f0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
25300 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
25310 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
25320 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
25330 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
25340 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
25350 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
25360 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
25370 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
25380 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
25390 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
253a0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
253b0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
253c0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
253d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
253e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
253f0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
25400 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
25410 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
25420 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
25430 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
25440 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
25450 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
25460 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
25470 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
25480 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
25490 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
254a0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
254b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
254c0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
254d0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
254e0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
254f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
25500 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
25510 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
25520 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
25530 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
25540 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
25550 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
25560 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
25570 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
25580 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
25590 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
255a0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
255b0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
255c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
255d0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
255e0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
255f0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
25600 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
25610 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
25620 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
25630 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
25640 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
25650 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
25660 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
25670 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
25680 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
25690 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
256a0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
256b0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
256c0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
256d0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
256e0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
256f0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
25700 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
25710 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
25720 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
25730 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
25740 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
25750 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
25760 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
25770 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
25780 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
25790 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
257a0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
257b0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
257c0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
257d0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
257e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
257f0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
25800 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
25810 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
25820 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
25830 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
25840 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
25850 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
25860 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
25870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
25880 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
25890 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
258a0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
258b0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
258c0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
258d0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
258e0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
258f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
25900 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
25910 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
25920 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25930 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
25940 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
25950 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
25960 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
25970 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
25980 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
25990 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
259a0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
259b0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
259c0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
259d0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
259e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
259f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
25a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25a10 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
25a20 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
25a30 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
25a40 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
25a50 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
25a60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
25a70 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
25a80 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
25a90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
25aa0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
25ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
25ac0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
25ad0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
25ae0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
25af0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
25b00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
25b10 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
25b20 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
25b30 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
25b40 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
25b50 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
25b60 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
25b70 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
25b80 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
25b90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
25ba0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
25bb0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
25bc0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
25bd0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
25be0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
25bf0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
25c00 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
25c10 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
25c20 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
25c30 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
25c40 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
25c50 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
25c60 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
25c70 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
25c80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
25c90 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
25ca0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
25cb0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
25cc0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
25cd0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
25ce0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
25cf0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25d00 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
25d10 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
25d20 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
25d30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
25d40 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
25d50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
25d60 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
25d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25d80 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
25d90 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
25da0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
25db0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25dc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
25dd0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
25de0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
25df0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
25e00 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
25e10 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
25e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
25e30 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
25e40 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
25e50 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
25e60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
25e70 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
25e80 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
25e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25ea0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
25eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25ec0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
25ed0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
25ee0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
25ef0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
25f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25f10 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
25f20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
25f30 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
25f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25f50 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
25f60 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
25f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25f80 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
25f90 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25fa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
25fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
25fc0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
25fd0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
25fe0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
25ff0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
26000 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
26010 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
26020 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
26030 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
26040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
26050 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
26060 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
26070 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
26080 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
26090 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
260a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
260b0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
260c0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
260d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
260e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
260f0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
26100 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
26110 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
26120 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
26130 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
26140 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
26150 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
26160 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
26170 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
26180 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
26190 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
261a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
261b0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
261c0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
261d0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
261e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
261f0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
26200 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
26210 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
26220 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
26230 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
26240 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
26250 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
26260 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26270 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
26280 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26290 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
262a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
262b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
262c0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
262d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
262e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
262f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
26300 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
26310 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
26320 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
26330 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
26340 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
26350 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26360 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
26370 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
26380 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
26390 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
263a0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
263b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
263c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
263d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
263e0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
263f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26400 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
26410 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
26420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
26430 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
26440 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26450 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
26460 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26470 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
26480 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
26490 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
264a0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
264b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
264c0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
264d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
264e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
264f0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
26500 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26510 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
26520 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
26530 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
26540 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
26550 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
26560 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68  s or.** or if th
26570 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
26580 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
26590 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
265a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
265b0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
265c0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
265d0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
265e0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
265f0 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
26600 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
26610 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
26620 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
26630 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
26640 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
26650 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
26660 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
26670 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
26680 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
26690 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
266a0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
266b0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
266c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
266d0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
266e0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
266f0 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
26700 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
26710 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
26720 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
26730 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
26740 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26750 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
26760 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26770 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
26780 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
26790 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
267a0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
267b0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
267c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
267d0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
267e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
267f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
26800 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
26810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26820 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
26830 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
26840 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
26850 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
26860 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
26870 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
26880 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
26890 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
268a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
268b0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
268c0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
268d0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
268e0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
268f0 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
26900 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
26910 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
26920 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
26930 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
26940 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
26950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
26960 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
26970 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
26980 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26990 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
269a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
269b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
269c0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
269d0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
269e0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
269f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
26a00 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
26a10 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
26a20 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
26a30 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
26a40 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
26a50 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
26a60 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
26a70 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
26a80 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
26a90 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
26aa0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
26ab0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
26ac0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
26ad0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
26ae0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
26af0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
26b00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
26b10 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
26b20 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
26b30 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26b40 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
26b50 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
26b60 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
26b70 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
26b80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
26b90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
26ba0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
26bb0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26bc0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
26bd0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
26be0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
26bf0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
26c00 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
26c10 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
26c20 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
26c30 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
26c40 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
26c50 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
26c60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
26c70 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
26c80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26c90 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
26ca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26cb0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
26cc0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
26cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26ce0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
26cf0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
26d00 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
26d10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
26d20 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
26d30 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
26d40 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
26d50 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
26d60 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
26d70 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
26d80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
26d90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26da0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
26db0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
26dc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
26dd0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
26de0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
26df0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
26e00 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
26e10 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
26e20 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
26e30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
26e40 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
26e50 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
26e60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
26e70 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
26e80 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
26e90 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
26ea0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
26eb0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
26ec0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
26ed0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
26ee0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
26ef0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
26f00 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
26f10 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
26f20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
26f30 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
26f40 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
26f50 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
26f60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26f70 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
26f80 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
26f90 2a 2a 20 74 68 65 20 74 68 65 20 73 65 63 6f 6e  ** the the secon
26fa0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
26fb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
26fc0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
26fd0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
26fe0 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
26ff0 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
27000 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
27010 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
27020 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
27030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27040 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
27050 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
27060 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
27070 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
27080 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
27090 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
270a0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
270b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
270c0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
270d0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
270e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
270f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
27100 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
27110 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
27120 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
27130 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
27140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
27150 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
27160 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27170 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
27180 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
27190 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
271a0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
271b0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
271c0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
271d0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
271e0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
271f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
27200 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
27210 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
27220 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
27230 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
27240 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
27250 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
27260 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
27270 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
27280 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
27290 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
272a0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
272b0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
272c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
272d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
272e0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
272f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
27300 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
27310 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
27320 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
27330 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
27340 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
27350 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
27360 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
27370 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
27380 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
27390 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
273a0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
273b0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
273c0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
273d0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
273e0 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
273f0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
27400 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
27410 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
27420 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
27430 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
27440 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
27450 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27460 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
27470 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
27480 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
27490 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
274a0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
274b0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
274c0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
274d0 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
274e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
274f0 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
27500 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
27510 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
27520 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
27530 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
27540 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
27550 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
27560 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
27570 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
27580 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
27590 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
275a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
275b0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
275c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
275d0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
275e0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
275f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
27600 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
27610 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
27620 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
27630 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
27640 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
27650 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
27660 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
27670 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
27680 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
27690 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
276a0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
276b0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
276c0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
276d0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
276e0 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
276f0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
27700 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
27710 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
27720 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
27730 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
27740 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
27750 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
27760 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
27770 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
27780 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
27790 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
277a0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
277b0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
277c0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
277d0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
277e0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
277f0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
27800 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
27810 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
27820 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
27830 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
27840 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
27850 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
27860 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
27870 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
27880 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
27890 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
278a0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
278b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
278c0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
278d0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
278e0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
278f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
27900 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
27910 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
27920 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
27930 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
27940 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
27950 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
27960 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
27970 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
27980 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
27990 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
279a0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
279b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
279c0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
279d0 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73 20 66 6f   NULL poiners fo
279e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
279f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
27a00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
27a10 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
27a20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
27a30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
27a40 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
27a50 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
27a60 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
27a70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
27a80 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
27a90 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
27aa0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
27ab0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
27ac0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
27ad0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
27ae0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
27af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27b00 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
27b10 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
27b20 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
27b30 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
27b40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
27b50 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
27b60 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
27b70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
27b80 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
27b90 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
27ba0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
27bb0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
27bc0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
27bd0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
27be0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
27bf0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
27c00 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
27c10 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
27c20 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
27c30 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
27c40 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
27c50 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
27c60 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
27c70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
27c80 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
27c90 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
27ca0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
27cb0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
27cc0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
27cd0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
27ce0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
27cf0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
27d00 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
27d10 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
27d20 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
27d30 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
27d40 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
27d50 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
27d60 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
27d70 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
27d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
27d90 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
27da0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
27db0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
27dc0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
27dd0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
27de0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
27df0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
27e00 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
27e10 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
27e20 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
27e30 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
27e40 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
27e50 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
27e60 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
27e70 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
27e80 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
27e90 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
27ea0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
27eb0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
27ec0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
27ed0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
27ee0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
27ef0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
27f00 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
27f10 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
27f20 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
27f30 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
27f40 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
27f50 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
27f60 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
27f70 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
27f80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
27f90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
27fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27fb0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
27fc0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
27fd0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
27fe0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
27ff0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
28000 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
28010 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
28020 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
28030 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
28040 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
28050 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
28060 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
28070 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
28080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
28090 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
280a0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
280b0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
280c0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
280d0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
280e0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
280f0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
28100 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
28110 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
28120 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
28130 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
28140 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
28150 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
28160 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
28170 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
28180 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
28190 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
281a0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
281b0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
281c0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
281d0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
281e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
281f0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
28200 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
28210 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
28220 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
28230 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
28240 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
28250 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
28260 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
28270 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
28280 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
28290 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
282a0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
282b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
282c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
282d0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
282e0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
282f0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
28300 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
28310 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
28320 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
28330 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
28340 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
28350 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
28360 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
28370 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
28380 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
28390 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
283a0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
283b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
283c0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
283d0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
283e0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
283f0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
28400 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
28410 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
28420 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
28430 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
28440 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
28450 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
28460 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
28470 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
28480 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
28490 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
284a0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
284b0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
284c0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
284d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
284e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
284f0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
28500 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
28510 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
28520 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
28530 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
28540 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
28550 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28560 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
28570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28580 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
28590 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
285a0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
285b0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
285c0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
285d0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
285e0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
285f0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
28600 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
28610 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
28620 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
28630 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
28640 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
28650 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
28660 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
28670 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
28680 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
28690 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
286a0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
286b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
286c0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
286d0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
286e0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
286f0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
28700 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
28710 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
28720 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
28730 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
28740 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
28750 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
28760 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
28770 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
28780 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
28790 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
287a0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
287b0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
287c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
287d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
287e0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
287f0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
28800 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
28810 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
28820 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
28830 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
28840 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
28850 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
28860 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
28870 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
28880 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
28890 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
288a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
288b0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
288c0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
288d0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
288e0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
288f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
28900 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
28910 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
28920 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
28930 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
28940 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
28950 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
28960 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
28970 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
28980 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
28990 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
289a0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
289b0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
289c0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
289d0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
289e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
289f0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
28a00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28a10 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
28a20 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
28a30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
28a40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
28a50 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
28a60 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
28a70 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
28a80 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
28a90 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
28aa0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
28ab0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28ac0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
28ad0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
28ae0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
28af0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
28b00 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
28b10 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
28b20 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
28b30 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
28b40 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
28b50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28b60 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
28b70 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
28b80 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
28b90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28ba0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
28bb0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
28bc0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
28bd0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
28be0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28bf0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
28c00 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
28c10 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
28c20 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
28c30 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
28c40 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
28c50 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
28c60 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
28c70 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
28c80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
28c90 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
28ca0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28cb0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
28cc0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
28cd0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
28ce0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
28cf0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
28d00 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
28d10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28d20 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
28d30 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
28d40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
28d50 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
28d60 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
28d70 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
28d80 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28d90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28da0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
28db0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
28dc0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
28dd0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
28de0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
28df0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
28e00 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
28e10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
28e20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
28e30 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
28e40 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
28e50 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
28e60 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
28e70 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
28e80 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
28e90 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
28ea0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
28eb0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
28ec0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
28ed0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
28ee0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
28ef0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
28f00 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
28f10 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
28f20 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
28f30 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
28f40 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
28f50 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
28f60 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
28f70 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
28f80 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
28f90 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
28fa0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
28fb0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
28fc0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
28fd0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
28fe0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
28ff0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
29000 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
29010 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
29020 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
29030 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
29040 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
29050 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
29060 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
29070 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29080 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
29090 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
290a0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
290b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
290c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
290d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
290e0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
290f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
29100 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
29110 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
29120 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
29130 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
29140 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
29150 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
29160 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
29170 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
29180 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
29190 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
291a0 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
291b0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
291c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
291d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
291e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
291f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
29200 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
29210 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
29220 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
29230 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
29240 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
29250 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29260 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
29270 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
29280 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
29290 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
292a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
292b0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
292c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
292d0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
292e0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
292f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
29300 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
29310 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
29320 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29330 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
29340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
29350 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29360 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
29370 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
29380 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
29390 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
293a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
293b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
293c0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
293d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
293e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
293f0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
29400 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
29410 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
29420 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
29430 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
29440 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
29450 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
29460 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
29470 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
29480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29490 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
294a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
294b0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
294c0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
294d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
294e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
294f0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
29500 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
29510 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
29520 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
29530 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29540 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
29550 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
29560 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
29570 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
29580 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29590 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
295a0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
295b0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
295c0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
295d0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
295e0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
295f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29600 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
29610 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
29620 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
29630 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
29640 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
29650 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
29660 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
29670 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
29680 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
29690 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
296a0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
296b0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
296c0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
296d0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
296e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
296f0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
29700 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
29710 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
29720 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
29730 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
29740 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29750 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
29760 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
29770 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
29780 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
29790 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
297a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
297b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
297c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
297d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
297e0 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
297f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
29800 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
29810 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  ory allocate err
29820 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
29830 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
29840 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
29850 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
29860 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
29870 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
29880 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
29890 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
298a0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
298b0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
298c0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
298d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
298e0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
298f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
29900 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
29910 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
29920 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
29930 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
29940 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
29950 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cation.)^.**.** 
29960 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
29970 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
29980 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
29990 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
299a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
299b0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
299c0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
299d0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
299e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
299f0 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
29a00 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
29a10 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
29a20 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
29a30 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
29a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
29a50 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
29a60 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
29a70 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
29a80 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
29a90 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
29aa0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
29ab0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
29ac0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
29ad0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
29ae0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
29af0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
29b00 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
29b10 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
29b20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
29b30 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
29b40 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
29b50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29b60 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
29b70 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
29b80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
29b90 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
29ba0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
29bb0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
29bc0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
29bd0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
29be0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
29bf0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
29c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
29c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
29c20 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
29c30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
29c40 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
29c50 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
29c60 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
29c70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
29c80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
29c90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
29ca0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
29cb0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
29cc0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
29cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29ce0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29cf0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
29d00 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
29d10 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
29d20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
29d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
29d40 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
29d50 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
29d60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29d70 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
29d80 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
29d90 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29da0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
29db0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
29dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
29dd0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
29de0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
29df0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29e00 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
29e10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29e20 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
29e30 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
29e40 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
29e50 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
29e60 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
29e70 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
29e80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
29e90 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
29ea0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
29eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29ec0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
29ed0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
29ee0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
29ef0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
29f00 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
29f10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
29f20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
29f30 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
29f40 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
29f50 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
29f60 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
29f70 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
29f80 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
29f90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
29fa0 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
29fb0 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
29fc0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
29fd0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
29fe0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
29ff0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
2a000 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
2a010 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
2a020 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
2a030 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
2a040 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
2a050 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
2a060 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
2a070 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2a080 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
2a090 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
2a0a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2a0b0 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
2a0c0 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
2a0d0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
2a0e0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
2a0f0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
2a100 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
2a110 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
2a120 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
2a130 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2a140 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
2a150 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
2a160 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
2a170 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2a180 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
2a190 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
2a1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a1b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a1c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2a1d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2a1e0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
2a1f0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
2a200 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
2a210 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
2a220 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
2a230 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
2a240 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
2a250 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2a260 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
2a270 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
2a280 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
2a290 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
2a2a0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
2a2b0 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
2a2c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
2a2d0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
2a2e0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
2a2f0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
2a300 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
2a310 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
2a320 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
2a330 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2a340 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2a350 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a360 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2a370 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
2a380 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2a390 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2a3a0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2a3b0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
2a3c0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
2a3d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a3e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a3f0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
2a400 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2a410 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2a420 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
2a430 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
2a440 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
2a450 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
2a460 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
2a470 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
2a480 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
2a490 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
2a4a0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2a4b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a4c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2a4d0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2a4e0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
2a4f0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2a500 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2a510 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
2a520 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
2a530 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
2a540 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
2a550 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
2a560 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
2a570 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
2a580 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
2a590 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
2a5a0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
2a5b0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
2a5c0 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
2a5d0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
2a5e0 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
2a5f0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
2a600 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
2a610 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
2a620 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
2a630 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2a640 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2a650 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2a660 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2a670 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2a680 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2a690 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2a6a0 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2a6b0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2a6c0 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
2a6d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a6e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2a6f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2a700 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2a710 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
2a720 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2a730 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2a740 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2a750 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a760 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2a770 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2a780 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2a790 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2a7a0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2a7b0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2a7c0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2a7d0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2a7e0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2a7f0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
2a800 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
2a810 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
2a820 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
2a830 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
2a840 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
2a850 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
2a860 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
2a870 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
2a880 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
2a890 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
2a8a0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
2a8b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2a8c0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
2a8d0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
2a8e0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
2a8f0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
2a900 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
2a910 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
2a920 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
2a930 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
2a940 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2a950 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
2a960 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
2a970 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
2a980 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
2a990 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
2a9a0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
2a9b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
2a9c0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
2a9d0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
2a9e0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
2a9f0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
2aa00 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
2aa10 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
2aa20 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
2aa30 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
2aa40 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
2aa50 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
2aa60 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
2aa70 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
2aa80 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2aa90 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
2aaa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
2aab0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
2aac0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2aad0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
2aae0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
2aaf0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
2ab00 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
2ab10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2ab20 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
2ab30 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
2ab40 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
2ab50 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
2ab60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2ab70 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
2ab80 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
2ab90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2aba0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2abb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2abc0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
2abd0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2abe0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
2abf0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
2ac00 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
2ac10 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
2ac20 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
2ac30 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
2ac40 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
2ac50 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2ac60 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2ac70 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2ac80 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
2ac90 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
2aca0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2acb0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2acc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
2acd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ace0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2acf0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2ad00 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2ad10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ad20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2ad30 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
2ad40 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
2ad50 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
2ad60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
2ad70 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
2ad80 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
2ad90 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
2ada0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2adb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2adc0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
2add0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
2ade0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
2adf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ae00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ae10 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
2ae20 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
2ae30 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
2ae40 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
2ae50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2ae60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
2ae70 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2ae80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2ae90 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
2aea0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2aeb0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2aec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2aed0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2aee0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
2aef0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
2af00 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
2af10 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
2af20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2af30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2af40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2af50 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
2af60 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
2af70 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
2af80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
2af90 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
2afa0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
2afb0 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
2afc0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2afd0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
2afe0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
2aff0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2b000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b010 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
2b020 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
2b030 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
2b040 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
2b050 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2b060 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
2b070 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2b080 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
2b090 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
2b0a0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2b0b0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2b0c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b0d0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
2b0e0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
2b0f0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
2b100 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2b110 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2b120 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2b130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b140 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
2b150 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2b160 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
2b170 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
2b180 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
2b190 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2b1a0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2b1b0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2b1c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2b1d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2b1e0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
2b1f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2b200 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
2b210 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2b220 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
2b230 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2b240 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
2b250 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
2b260 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2b270 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
2b280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2b290 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2b2a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2b2b0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
2b2c0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
2b2d0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
2b2e0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
2b2f0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
2b300 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
2b310 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
2b320 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
2b330 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
2b340 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
2b350 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
2b360 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b370 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2b380 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2b390 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2b3a0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2b3b0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2b3c0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2b3d0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2b3e0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
2b3f0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
2b400 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
2b410 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
2b420 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2b430 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2b440 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2b450 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b460 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
2b470 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
2b480 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
2b490 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b4a0 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  t_toobig() inter
2b4b0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
2b4c0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
2b4d0 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
2b4e0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
2b4f0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
2b500 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
2b510 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2b520 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
2b530 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
2b540 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2b550 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2b560 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2b570 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
2b580 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
2b590 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b5a0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
2b5b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2b5c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2b5d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2b5e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b5f0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
2b600 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
2b610 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2b620 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2b630 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2b640 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b650 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
2b660 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2b670 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2b680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b690 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b6a0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
2b6b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2b6c0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2b6d0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2b6e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2b6f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2b700 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
2b710 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2b720 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2b730 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b740 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2b750 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2b760 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b770 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2b780 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2b790 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
2b7a0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
2b7b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2b7c0 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
2b7d0 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
2b7e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b7f0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2b800 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b810 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
2b820 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
2b830 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
2b840 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
2b850 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2b860 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
2b870 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
2b880 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
2b890 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
2b8a0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
2b8b0 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2b8c0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2b8d0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2b8e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b8f0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2b900 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2b910 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
2b920 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2b930 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2b940 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2b950 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2b960 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
2b970 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
2b980 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
2b990 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
2b9a0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2b9b0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2b9c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
2b9d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b9e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2b9f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2ba00 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
2ba10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
2ba20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
2ba30 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
2ba40 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
2ba50 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
2ba60 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
2ba70 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
2ba80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
2ba90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
2baa0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2bab0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2bac0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2bad0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2bae0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2baf0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2bb00 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
2bb10 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
2bb20 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
2bb30 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
2bb40 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
2bb50 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
2bb60 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
2bb70 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
2bb80 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2bb90 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2bba0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bbb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2bbc0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
2bbd0 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
2bbe0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2bbf0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2bc00 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
2bc10 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
2bc20 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
2bc30 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2bc40 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
2bc50 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
2bc60 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
2bc70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
2bc80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
2bc90 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
2bca0 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
2bcb0 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
2bcc0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
2bcd0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2bce0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2bcf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2bd00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2bd10 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2bd20 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2bd30 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2bd40 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2bd50 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2bd60 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
2bd70 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2bd80 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
2bd90 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
2bda0 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
2bdb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2bdc0 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
2bdd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
2bde0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2bdf0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
2be00 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
2be10 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2be20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2be30 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
2be40 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
2be50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2be60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
2be70 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
2be80 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
2be90 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
2bea0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2beb0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
2bec0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
2bed0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
2bee0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
2bef0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
2bf00 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
2bf10 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
2bf20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
2bf30 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
2bf40 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2bf50 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
2bf60 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
2bf70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bf80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
2bf90 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
2bfa0 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
2bfb0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2bfc0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2bfd0 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
2bfe0 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
2bff0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2c000 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
2c010 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
2c020 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2c030 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
2c040 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
2c050 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
2c060 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
2c070 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
2c080 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
2c090 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c0a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
2c0b0 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
2c0c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2c0d0 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
2c0e0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2c0f0 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
2c100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2c110 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2c120 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2c130 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2c140 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2c150 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2c160 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2c170 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
2c180 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c190 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
2c1a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2c1b0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
2c1c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c1d0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
2c1e0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2c1f0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
2c200 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c210 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
2c220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2c230 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c240 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
2c250 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c260 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2c270 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
2c280 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
2c290 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2c2a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2c2b0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2c2c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2c2d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2c2e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
2c2f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
2c300 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
2c310 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2c320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c330 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c340 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
2c350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2c360 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
2c370 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2c380 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c390 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
2c3a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2c3b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2c3c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2c3d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c3e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2c3f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2c400 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2c410 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2c420 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2c430 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
2c440 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c450 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2c460 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2c470 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c480 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
2c490 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2c4a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2c4b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2c4c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
2c4d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2c4e0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2c4f0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
2c500 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
2c510 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
2c520 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
2c530 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
2c540 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
2c550 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
2c560 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2c570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c580 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
2c590 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
2c5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2c5b0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2c5c0 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
2c5d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
2c5e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c5f0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
2c600 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c610 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
2c620 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
2c630 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
2c640 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
2c650 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c660 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
2c670 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
2c680 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
2c690 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
2c6a0 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
2c6b0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
2c6c0 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
2c6d0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
2c6e0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2c6f0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
2c700 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
2c710 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
2c720 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
2c730 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
2c740 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2c750 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
2c760 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
2c770 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2c780 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
2c790 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2c7a0 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
2c7b0 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
2c7c0 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
2c7d0 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
2c7e0 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
2c7f0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
2c800 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2c810 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
2c820 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
2c830 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
2c840 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
2c850 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
2c860 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
2c870 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
2c880 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
2c890 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2c8a0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
2c8b0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2c8c0 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
2c8d0 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
2c8e0 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
2c8f0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
2c900 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
2c910 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
2c920 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
2c930 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2c940 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
2c950 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
2c960 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
2c970 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2c980 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2c990 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
2c9a0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2c9b0 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
2c9c0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
2c9d0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
2c9e0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
2c9f0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
2ca00 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
2ca10 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
2ca20 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
2ca30 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
2ca40 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
2ca50 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
2ca60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
2ca70 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
2ca80 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2ca90 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2caa0 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
2cab0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
2cac0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
2cad0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
2cae0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
2caf0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
2cb00 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
2cb10 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
2cb20 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
2cb30 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
2cb40 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
2cb50 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
2cb60 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
2cb70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
2cb80 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2cb90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2cba0 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
2cbb0 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
2cbc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2cbd0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
2cbe0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
2cbf0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2cc00 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
2cc10 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
2cc20 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
2cc30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
2cc40 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
2cc50 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
2cc60 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
2cc70 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
2cc80 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
2cc90 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
2cca0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
2ccb0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
2ccc0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
2ccd0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
2cce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
2ccf0 74 20 61 6c 77 61 79 20 72 65 74 75 72 6e 20 74  t alway return t
2cd00 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
2cd10 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
2cd20 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
2cd30 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
2cd40 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
2cd50 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
2cd60 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
2cd70 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
2cd80 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
2cd90 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
2cda0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
2cdb0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
2cdc0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
2cdd0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
2cde0 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
2cdf0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
2ce00 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
2ce10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
2ce20 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
2ce30 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
2ce40 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
2ce50 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
2ce60 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
2ce70 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
2ce80 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
2ce90 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
2cea0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
2ceb0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
2cec0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
2ced0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
2cee0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
2cef0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2cf00 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
2cf10 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
2cf20 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
2cf30 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
2cf40 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
2cf50 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
2cf60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2cf70 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
2cf80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2cf90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2cfa0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2cfb0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
2cfc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2cfd0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
2cfe0 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
2cff0 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
2d000 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
2d010 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
2d020 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
2d030 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
2d040 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
2d050 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
2d060 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
2d070 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2d080 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
2d090 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
2d0a0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2d0b0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2d0c0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
2d0d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d0e0 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
2d0f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2d100 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
2d110 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
2d120 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
2d130 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
2d140 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d150 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
2d160 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
2d170 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2d180 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
2d190 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d1a0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
2d1b0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
2d1c0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
2d1d0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
2d1e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
2d1f0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2d200 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2d210 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
2d220 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
2d230 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
2d240 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
2d250 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
2d260 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
2d270 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
2d280 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
2d290 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
2d2a0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
2d2b0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
2d2c0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
2d2d0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
2d2e0 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
2d2f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
2d300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2d310 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2d320 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
2d330 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
2d340 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
2d350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d360 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2d370 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
2d380 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2d390 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2d3a0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
2d3b0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
2d3c0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2d3d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2d3e0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
2d3f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2d400 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2d410 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d420 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2d430 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2d440 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2d450 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2d460 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2d470 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2d480 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
2d490 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2d4a0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
2d4b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d4c0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2d4d0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
2d4e0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
2d4f0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2d500 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
2d510 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2d520 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2d530 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2d540 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2d550 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
2d560 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
2d570 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
2d580 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
2d590 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
2d5a0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
2d5b0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
2d5c0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
2d5d0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
2d5e0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
2d5f0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
2d600 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2d610 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
2d620 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2d630 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
2d640 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2d650 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
2d660 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
2d670 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
2d680 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
2d690 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
2d6a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
2d6b0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2d6c0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
2d6d0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
2d6e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2d6f0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
2d700 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
2d710 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
2d720 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2d730 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
2d740 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
2d750 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
2d760 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
2d770 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
2d780 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
2d790 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
2d7a0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
2d7b0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
2d7c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2d7d0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
2d7e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
2d7f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d800 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
2d810 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
2d820 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
2d830 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
2d840 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
2d850 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
2d860 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
2d870 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
2d880 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
2d890 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2d8a0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
2d8b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2d8c0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
2d8d0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2d8e0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
2d8f0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
2d900 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
2d910 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
2d920 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
2d930 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
2d940 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
2d950 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2d960 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2d970 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
2d980 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
2d990 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
2d9a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
2d9b0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
2d9c0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
2d9d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
2d9e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
2d9f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2da00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2da10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2da20 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2da30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2da40 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
2da50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2da60 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
2da70 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2da80 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2da90 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
2daa0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
2dab0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
2dac0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2dad0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
2dae0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
2daf0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2db00 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
2db10 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
2db20 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
2db30 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
2db40 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
2db50 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
2db60 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
2db70 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
2db80 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
2db90 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
2dba0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
2dbb0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2dbc0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2dbd0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2dbe0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2dbf0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2dc00 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2dc10 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
2dc20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2dc30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2dc40 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2dc50 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2dc60 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2dc70 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2dc80 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2dc90 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
2dca0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
2dcb0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
2dcc0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
2dcd0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
2dce0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
2dcf0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
2dd00 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
2dd10 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
2dd20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
2dd30 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
2dd40 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2dd50 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2dd60 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2dd70 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2dd80 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2dd90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2dda0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
2ddb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ddc0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ddd0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2dde0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2ddf0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2de00 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
2de10 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2de20 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2de30 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2de40 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
2de50 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
2de60 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
2de70 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
2de80 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
2de90 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
2dea0 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
2deb0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
2dec0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
2ded0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
2dee0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
2def0 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
2df00 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
2df10 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
2df20 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
2df30 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
2df40 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
2df50 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
2df60 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
2df70 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
2df80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
2df90 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
2dfa0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
2dfb0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
2dfc0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
2dfd0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
2dfe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dff0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
2e000 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
2e010 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
2e020 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
2e030 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
2e040 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2e050 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
2e060 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
2e070 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
2e080 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
2e090 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
2e0a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2e0b0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
2e0c0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
2e0d0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
2e0e0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
2e0f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
2e100 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
2e110 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
2e120 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
2e130 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
2e140 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
2e150 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2e160 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2e170 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
2e180 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
2e190 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
2e1a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2e1b0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
2e1c0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
2e1d0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
2e1e0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
2e1f0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
2e200 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
2e210 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
2e220 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
2e230 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
2e240 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
2e250 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
2e260 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
2e270 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
2e280 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
2e290 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2e2a0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
2e2b0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
2e2c0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
2e2d0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
2e2e0 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
2e2f0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
2e300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e310 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
2e320 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2e330 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
2e340 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
2e350 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
2e360 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2e370 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
2e380 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
2e390 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
2e3a0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
2e3b0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
2e3c0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
2e3d0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
2e3e0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
2e3f0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
2e400 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
2e410 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
2e420 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
2e430 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
2e440 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
2e450 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2e460 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
2e470 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
2e480 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
2e490 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
2e4a0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
2e4b0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2e4c0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2e4d0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
2e4e0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
2e4f0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
2e500 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
2e510 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2e520 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2e530 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
2e540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2e550 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
2e560 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
2e570 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
2e580 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
2e590 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
2e5a0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
2e5b0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
2e5c0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
2e5d0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
2e5e0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
2e5f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
2e600 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
2e610 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
2e620 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2e630 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
2e640 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
2e650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
2e660 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2e670 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
2e680 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2e690 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
2e6a0 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
2e6b0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2e6c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2e6d0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
2e6e0 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
2e6f0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2e700 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
2e710 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
2e720 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
2e730 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2e740 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
2e750 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
2e760 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
2e770 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
2e780 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
2e790 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
2e7a0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
2e7b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e7c0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
2e7d0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
2e7e0 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
2e7f0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
2e800 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
2e810 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
2e820 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2e830 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2e840 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2e850 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
2e860 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
2e870 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2e880 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
2e890 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
2e8a0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
2e8b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
2e8c0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
2e8d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2e8e0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
2e8f0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
2e900 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
2e910 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
2e920 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2e930 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
2e940 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
2e950 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
2e960 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
2e970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e980 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
2e990 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
2e9a0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
2e9b0 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
2e9c0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
2e9d0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
2e9e0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
2e9f0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
2ea00 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
2ea10 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
2ea20 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
2ea30 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
2ea40 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
2ea50 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
2ea60 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
2ea70 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
2ea80 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
2ea90 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
2eaa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
2eab0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
2eac0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
2ead0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
2eae0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
2eaf0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
2eb00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
2eb10 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
2eb20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2eb30 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
2eb40 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
2eb50 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
2eb60 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
2eb70 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
2eb80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2eb90 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
2eba0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
2ebb0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
2ebc0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
2ebd0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
2ebe0 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
2ebf0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
2ec00 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
2ec10 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2ec20 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
2ec30 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
2ec40 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
2ec50 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2ec60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2ec70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
2ec80 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
2ec90 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
2eca0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
2ecb0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
2ecc0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
2ecd0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2ece0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
2ecf0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
2ed00 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
2ed10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ed20 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
2ed30 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
2ed40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
2ed50 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
2ed60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ed70 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
2ed80 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2ed90 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
2eda0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2edb0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
2edc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2edd0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
2ede0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2edf0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
2ee00 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
2ee10 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
2ee20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
2ee30 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
2ee40 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
2ee50 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
2ee60 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
2ee70 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2ee80 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
2ee90 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
2eea0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2eeb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
2eec0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2eed0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
2eee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eef0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
2ef00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ef10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ef20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
2ef30 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
2ef40 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
2ef50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ef60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2ef70 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
2ef80 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
2ef90 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2efa0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2efb0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
2efc0 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
2efd0 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
2efe0 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
2eff0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
2f000 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
2f010 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
2f020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f030 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
2f040 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
2f050 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2f060 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
2f070 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
2f080 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2f090 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
2f0a0 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
2f0b0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
2f0c0 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74  r..*/.sqlite3_st
2f0d0 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
2f0e0 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
2f0f0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
2f100 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f110 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
2f120 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
2f130 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2f140 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2f150 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2f160 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2f170 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2f180 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2f190 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2f1a0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2f1b0 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
2f1c0 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
2f1d0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2f1e0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2f1f0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2f200 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2f210 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2f220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f230 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
2f240 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
2f250 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2f260 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2f270 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2f280 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
2f290 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2f2a0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
2f2b0 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
2f2c0 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
2f2d0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2f2e0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2f2f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2f300 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2f310 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2f320 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2f330 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2f340 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
2f350 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
2f360 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
2f370 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
2f380 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
2f390 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
2f3a0 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
2f3b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
2f3c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
2f3d0 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
2f3e0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
2f3f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f400 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2f410 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
2f420 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2f430 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
2f440 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
2f450 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
2f460 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2f470 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
2f480 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
2f490 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2f4a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
2f4b0 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
2f4c0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
2f4d0 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
2f4e0 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
2f4f0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
2f500 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2f510 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2f520 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2f530 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f540 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2f550 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2f560 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2f570 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2f580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f590 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2f5a0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2f5b0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2f5c0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2f5d0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2f5e0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2f5f0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2f600 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2f610 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2f620 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2f630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f640 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2f650 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2f660 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2f670 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f680 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2f690 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2f6a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2f6b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69  aph..**.** ^Regi
2f6c0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2f6d0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2f6e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2f6f0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63  *.** ^When the c
2f700 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
2f710 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ack routine retu
2f720 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43  rns zero, the [C
2f730 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74  OMMIT].** operat
2f740 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74  ion is allowed t
2f750 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61  o continue norma
2f760 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f  lly.  ^If the co
2f770 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74  mmit hook.** ret
2f780 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
2f790 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  hen the [COMMIT]
2f7a0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2f7b0 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  to a [ROLLBACK].
2f7c0 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2f7d0 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65  k hook is invoke
2f7e0 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20  d on a rollback 
2f7f0 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f  that results fro
2f800 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f  m a commit.** ho
2f810 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e  ok returning non
2f820 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69  -zero, just as i
2f830 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20  t would be with 
2f840 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61  any other rollba
2f850 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  ck..**.** ^For t
2f860 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2f870 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2f880 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2f890 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2f8a0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2f8b0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2f8c0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2f8d0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2f8e0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2f8f0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2f900 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2f910 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2f920 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2f930 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2f940 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2f950 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
2f960 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2f970 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2f980 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f990 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
2f9a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
2f9b0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
2f9c0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69  update_hook()] i
2f9d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69  nterface..*/.voi
2f9e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
2f9f0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
2fa00 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
2fa10 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
2fa20 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2fa30 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
2fa40 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
2fa50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
2fa60 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
2fa70 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
2fa80 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2fa90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
2faa0 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
2fab0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2fac0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
2fad0 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
2fae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2faf0 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64  tion] identified
2fb00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
2fb10 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  gument.** to be 
2fb20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2fb30 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
2fb40 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
2fb50 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  eleted..** ^Any 
2fb60 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2fb70 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2fb80 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2fb90 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2fba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2fbb0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
2fbc0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  en..**.** ^The s
2fbd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2fbe0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2fbf0 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
2fc00 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20  nvoke when a.** 
2fc10 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
2fc20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
2fc30 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ted..** ^The fir
2fc40 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2fc50 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2fc60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
2fc70 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
2fc80 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
2fc90 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65  _hook()..** ^The
2fca0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
2fcb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2fcc0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
2fcd0 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
2fce0 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
2fcf0 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
2fd00 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
2fd10 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
2fd20 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
2fd30 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2fd40 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  d..** ^The third
2fd50 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
2fd60 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
2fd70 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
2fd80 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  inters to the.**
2fd90 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
2fda0 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
2fdb0 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
2fdc0 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69   row..** ^The fi
2fdd0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
2fde0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72  ameter is the [r
2fdf0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77  owid] of the row
2fe00 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73  ..** ^In the cas
2fe10 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
2fe20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77  this is the [row
2fe30 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70  id] after the up
2fe40 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  date takes place
2fe50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70  ..**.** ^(The up
2fe60 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
2fe70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
2fe80 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
2fe90 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
2fea0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
2feb0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
2fec0 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e  ite_sequence).)^
2fed0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  .**.** ^In the c
2fee0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
2fef0 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74  ation, the updat
2ff00 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74  e hook.** is not
2ff10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75   invoked when du
2ff20 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61  plication rows a
2ff30 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75  re deleted becau
2ff40 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20  se of an.** [ON 
2ff50 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f  CONFLICT | ON CO
2ff60 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20  NFLICT REPLACE] 
2ff70 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73  clause.  ^Nor is
2ff80 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2ff90 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  .** invoked when
2ffa0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2ffb0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75  d using the [tru
2ffc0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
2ffd0 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65  on]..** The exce
2ffe0 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69  ptions defined i
2fff0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
30000 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
30010 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
30020 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
30030 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
30040 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61   hook implementa
30050 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
30060 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
30070 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
30080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30090 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
300a0 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
300b0 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ok.  Any actions
300c0 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
300d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
300e0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
300f0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
30100 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
30110 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
30120 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
30130 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
30140 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
30150 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
30160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30170 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
30180 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
30190 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
301a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
301b0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
301c0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
301d0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
301e0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ph..**.** ^The s
301f0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
30200 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
30210 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  on.** returns th
30220 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
30230 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
30240 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  all.** on the sa
30250 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
30260 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
30270 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
30280 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a  irst call on D..
30290 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
302a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
302b0 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
302c0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
302d0 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
302e0 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20  rfaces..*/.void 
302f0 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
30300 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
30310 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
30320 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
30330 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
30340 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
30350 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
30360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
30370 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
30380 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
30390 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  che.** KEYWORDS:
303a0 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a   {shared cache}.
303b0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
303c0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
303d0 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
303e0 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
303f0 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
30400 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
30410 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
30420 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30430 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
30440 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
30450 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
30460 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
30470 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
30480 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
30490 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
304a0 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
304b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68  e.)^.**.** ^Cach
304c0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
304d0 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
304e0 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
304f0 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
30500 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
30510 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
30520 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
30530 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
30540 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
30550 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
30560 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
30570 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
30580 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
30590 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
305a0 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
305b0 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
305c0 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
305d0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
305e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
305f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
30600 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
30610 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
30620 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
30630 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
30640 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
30650 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
30660 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
30670 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
30680 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e  y were opened.)^
30690 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
306a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
306b0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
306c0 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
306d0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
306e0 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
306f0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
30700 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
30710 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a  otherwise.)^.**.
30720 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65  ** ^Shared cache
30730 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
30740 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
30750 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
30760 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
30770 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
30780 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
30790 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
307a0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
307b0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
307c0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
307d0 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
307e0 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
307f0 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69  Cache Mode].*/.i
30800 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
30810 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
30820 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
30830 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
30840 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
30850 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
30860 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30870 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
30880 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
30890 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
308a0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
308b0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
308c0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
308d0 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
308e0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
308f0 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d  ase library.   M
30900 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61  emory used to ca
30910 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  che database.** 
30920 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
30930 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
30940 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f  an example of no
30950 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
30960 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ry..** ^sqlite3_
30970 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
30980 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
30990 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
309a0 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
309b0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
309c0 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
309d0 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
309e0 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ested..** ^The s
309f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
30a00 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20  emory() routine 
30a10 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72  is a no-op retur
30a20 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20  ning zero.** if 
30a30 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f  SQLite is not co
30a40 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
30a50 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
30a60 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
30a70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
30a80 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
30a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30aa0 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
30ab0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
30ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30ad0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
30ae0 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  it64() interface
30af0 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65   sets and/or que
30b00 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ries the.** soft
30b10 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
30b20 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
30b30 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
30b40 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
30b50 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ite..** ^SQLite 
30b60 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20  strives to keep 
30b70 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c  heap memory util
30b80 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68  ization below th
30b90 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c  e soft heap.** l
30ba0 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67  imit by reducing
30bb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
30bc0 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65  ages held in the
30bd0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
30be0 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73  s heap memory us
30bf0 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20  ages approaches 
30c00 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  the limit..** ^T
30c10 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30c20 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63  it is "soft" bec
30c30 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68  ause even though
30c40 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20   SQLite strives 
30c50 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77  to stay.** below
30c60 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77   the limit, it w
30c70 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c  ill exceed the l
30c80 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e  imit rather than
30c90 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20   generate.** an 
30ca0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65  [SQLITE_NOMEM] e
30cb0 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  rror.  In other 
30cc0 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20  words, the soft 
30cd0 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69  heap limit .** i
30ce0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
30cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
30d00 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
30d10 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
30d20 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65  limit64() is the
30d30 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
30d40 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
30d50 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
30d60 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75  l.  ^If the argu
30d70 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69  ment N is negati
30d80 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68  ve.** then no ch
30d90 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20  ange is made to 
30da0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
30db0 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  mit.  Hence, the
30dc0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65   current.** size
30dd0 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   of the soft hea
30de0 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64  p limit can be d
30df0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76  etermined by inv
30e00 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
30e10 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
30e20 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61  64() with a nega
30e30 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tive argument..*
30e40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
30e50 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20  ument N is zero 
30e60 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65  then the soft he
30e70 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61  ap limit is disa
30e80 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  bled..**.** ^(Th
30e90 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
30ea0 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65  t is not enforce
30eb0 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  d in the current
30ec0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
30ed0 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ** if one or mor
30ee0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63  e of following c
30ef0 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72  onditions are tr
30f00 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ue:.**.** <ul>.*
30f10 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20  * <li> The soft 
30f20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65  heap limit is se
30f30 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c  t to zero..** <l
30f40 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  i> Memory accoun
30f50 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  ting is disabled
30f60 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61   using a combina
30f70 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  tion of the.**  
30f80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
30f90 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
30fa0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e  FIG_MEMSTATUS],.
30fb0 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f  ..) start-time o
30fc0 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ption and.**    
30fd0 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45    the [SQLITE_DE
30fe0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
30ff0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
31000 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e  tion..** <li> An
31010 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67   alternative pag
31020 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
31030 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66  tation is specif
31040 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
31050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
31060 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
31070 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a  _PCACHE],...)..*
31080 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
31090 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
310a0 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
310b0 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
310c0 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
310d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
310e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
310f0 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
31100 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
31110 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
31120 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
31130 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
31140 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
31150 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
31160 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
31170 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
31180 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
31190 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
311a0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
311b0 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
311c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
311d0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
311e0 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
311f0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
31200 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
31210 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
31220 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
31230 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
31240 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
31250 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
31260 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
31270 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
31280 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
31290 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
312a0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
312b0 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
312c0 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
312d0 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
312e0 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
312f0 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
31300 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
31310 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
31320 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
31330 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
31340 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
31350 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31360 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
31370 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
31380 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
31390 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
313a0 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
313b0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
313c0 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
313d0 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
313e0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
313f0 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
31400 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
31410 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
31420 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
31430 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
31440 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
31450 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
31460 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
31470 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
31480 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
31490 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
314a0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
314b0 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
314c0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
314d0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
314e0 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
314f0 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
31500 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
31510 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
31520 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
31530 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
31540 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
31550 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
31560 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
31570 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
31580 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
31590 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
315a0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
315b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
315c0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
315d0 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
315e0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
315f0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
31600 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
31610 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
31620 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
31630 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
31640 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
31650 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
31660 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
31670 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
31680 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31690 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
316a0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
316b0 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
316c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
316d0 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
316e0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
316f0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
31700 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
31710 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
31720 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
31730 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
31740 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
31750 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
31760 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
31770 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
31780 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
31790 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
317a0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
317b0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
317c0 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
317d0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
317e0 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
317f0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
31800 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
31810 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
31820 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
31830 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
31840 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
31850 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
31860 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
31870 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
31880 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31890 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
318a0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
318b0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
318c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
318d0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
318e0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
318f0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
31900 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
31910 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
31920 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
31930 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
31940 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
31950 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
31960 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
31970 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
31980 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
31990 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
319a0 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
319b0 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
319c0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
319d0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
319e0 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
319f0 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
31a00 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
31a10 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
31a20 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
31a30 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
31a40 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
31a50 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
31a60 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
31a70 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
31a80 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
31a90 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
31aa0 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
31ab0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
31ac0 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
31ad0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31ae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
31af0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
31b00 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
31b10 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
31b20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
31b30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
31b40 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
31b50 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
31b60 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
31b70 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
31b80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
31b90 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
31ba0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
31bb0 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
31bc0 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
31bd0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
31be0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
31bf0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
31c00 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
31c10 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
31c20 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
31c30 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
31c40 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
31c50 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
31c60 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
31c70 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
31c80 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
31c90 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
31ca0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
31cb0 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
31cc0 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
31cd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
31ce0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
31cf0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
31d00 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
31d10 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
31d20 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
31d30 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
31d40 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
31d50 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
31d60 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
31d70 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
31d80 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
31d90 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
31da0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
31db0 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
31dc0 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
31dd0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
31de0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
31df0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
31e00 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
31e10 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
31e20 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
31e30 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
31e40 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
31e50 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
31e60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31e70 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
31e80 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
31e90 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
31ea0 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
31eb0 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
31ec0 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
31ed0 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
31ee0 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
31ef0 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
31f00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
31f10 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
31f20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
31f30 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
31f40 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
31f50 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
31f60 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
31f70 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
31f80 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
31f90 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
31fa0 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
31fb0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31fc0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
31fd0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
31fe0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
31ff0 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
32000 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
32010 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
32020 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
32030 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
32040 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
32050 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
32060 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
32070 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
32080 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
32090 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
320a0 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
320b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
320c0 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
320d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
320e0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
320f0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
32100 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
32110 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
32120 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
32130 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
32140 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
32150 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
32160 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
32170 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
32180 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
32190 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
321a0 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
321b0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
321c0 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
321d0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
321e0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
321f0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
32200 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
32210 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
32220 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
32230 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
32240 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
32250 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
32260 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
32270 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
32280 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
32290 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
322a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
322b0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
322c0 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
322d0 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
322e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
322f0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
32300 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
32310 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
32320 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
32330 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
32340 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
32350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
32360 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
32370 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
32380 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
32390 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
323a0 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
323b0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
323c0 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
323d0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
323e0 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
323f0 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
32400 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
32410 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
32420 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
32430 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
32440 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
32450 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
32460 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
32470 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32480 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
32490 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
324a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
324b0 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
324c0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
324d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
324e0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
324f0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
32500 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
32510 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
32520 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
32530 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
32540 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
32550 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
32560 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
32570 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
32580 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
32590 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
325a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
325b0 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
325c0 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
325d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
325e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
325f0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
32600 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
32610 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
32620 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
32630 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
32640 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
32650 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
32660 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
32670 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
32680 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
32690 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
326a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
326b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
326c0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
326d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
326e0 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
326f0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
32700 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
32710 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
32720 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
32730 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
32740 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
32750 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
32760 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
32770 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
32780 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
32790 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
327a0 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
327b0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
327c0 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
327d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
327e0 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
327f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32800 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
32810 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
32820 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
32830 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
32840 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
32850 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
32860 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
32870 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
32880 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
32890 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
328a0 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
328b0 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
328c0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
328d0 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
328e0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
328f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
32900 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
32910 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
32920 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
32930 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
32940 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
32950 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
32960 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
32970 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
32980 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
32990 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
329a0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
329b0 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
329c0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
329d0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
329e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
329f0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
32a00 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
32a10 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
32a20 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
32a30 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
32a40 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
32a50 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
32a60 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
32a70 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
32a80 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c  ly Load Statical
32a90 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73  ly Linked Extens
32aa0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
32ab0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
32ac0 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  s the xEntryPoin
32ad0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  t() function to 
32ae0 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a  be invoked for.*
32af0 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61  * each new [data
32b00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32b10 20 74 68 61 74 20 69 73 20 63 72 65 61 74 65 64   that is created
32b20 2e 20 20 54 68 65 20 69 64 65 61 20 68 65 72 65  .  The idea here
32b30 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74   is that.** xEnt
32b40 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65  ryPoint() is the
32b50 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72   entry point for
32b60 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69   a statically li
32b70 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78 74 65  nked SQLite exte
32b80 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  nsion.** that is
32b90 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63   to be automatic
32ba0 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f  ally loaded into
32bb0 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73   all new databas
32bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  e connections..*
32bd0 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75  *.** ^(Even thou
32be0 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  gh the function 
32bf0 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20  prototype shows 
32c00 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74  that xEntryPoint
32c10 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61  () takes.** no a
32c20 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74  rguments and ret
32c30 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74  urns void, SQLit
32c40 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79  e invokes xEntry
32c50 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74 68 72  Point() with thr
32c60 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  ee.** arguments 
32c70 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e 64 20  and expects and 
32c80 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 61  integer result a
32c90 73 20 69 66 20 74 68 65 20 73 69 67 6e 61 74 75  s if the signatu
32ca0 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74  re of the.** ent
32cb0 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61  ry point where a
32cc0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
32cd0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
32ce0 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e  e>.** &nbsp;  in
32cf0 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a  t xEntryPoint(.*
32d00 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71 6c 69  * &nbsp;    sqli
32d10 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73  te3 *db,.** &nbs
32d20 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72  p;    const char
32d30 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20   **pzErrMsg,.** 
32d40 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20  &nbsp;    const 
32d50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
32d60 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54 68  pi_routines *pTh
32d70 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29  unk.** &nbsp;  )
32d80 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
32d90 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
32da0 20 49 66 20 74 68 65 20 78 45 6e 74 72 79 50 6f   If the xEntryPo
32db0 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f  int routine enco
32dc0 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f 72 2c  unters an error,
32dd0 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20   it should make 
32de0 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69  *pzErrMsg.** poi
32df0 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72  nt to an appropr
32e00 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
32e10 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66 72 6f  ge (obtained fro
32e20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
32e30 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65  tf()]).** and re
32e40 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  turn an appropri
32e50 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
32e60 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73 75 72  .  ^SQLite ensur
32e70 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72 4d 73  es that *pzErrMs
32e80 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66  g.** is NULL bef
32e90 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 65 20  ore calling the 
32ea0 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20 20  xEntryPoint().  
32eb0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76  ^SQLite will inv
32ec0 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  oke.** [sqlite3_
32ed0 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72  free()] on *pzEr
32ee0 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e 74 72  rMsg after xEntr
32ef0 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
32f00 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45  .  ^If any.** xE
32f10 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
32f20 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  rns an error, th
32f30 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
32f40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
32f50 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  n16()],.** or [s
32f60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
32f70 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72 6f 76  ] call that prov
32f80 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72 79 50  oked the xEntryP
32f90 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61 69 6c  oint() will fail
32fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
32fb0 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
32fc0 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74 68 20  tension(X) with 
32fd0 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 58  an entry point X
32fe0 20 74 68 61 74 20 69 73 20 61 6c 72 65 61 64 79   that is already
32ff0 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74 20  .** on the list 
33000 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  of automatic ext
33010 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68 61 72  ensions is a har
33020 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f  mless no-op. ^No
33030 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
33040 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d  will be called m
33050 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f  ore than once fo
33060 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
33070 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
33080 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  is opened..**.**
33090 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
330a0 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
330b0 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
330c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
330d0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
330e0 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76  (*xEntryPoint)(v
330f0 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid));../*.** CA
33100 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
33110 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
33120 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
33130 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
33140 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74  disables all aut
33150 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
33160 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  s previously.** 
33170 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
33180 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
33190 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
331a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
331b0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
331c0 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  n(void);../*.** 
331d0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
331e0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
331f0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
33200 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
33210 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
33220 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
33230 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
33240 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
33250 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
33260 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
33270 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
33280 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
33290 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
332a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
332b0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
332c0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
332d0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
332e0 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
332f0 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
33300 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
33310 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
33320 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
33330 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
33340 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
33350 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
33360 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
33370 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
33380 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
33390 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
333a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
333b0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
333c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
333d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
333e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
333f0 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
33400 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
33410 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
33420 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
33430 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
33440 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
33450 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ble Object.** KE
33460 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
33470 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
33480 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
33490 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
334a0 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
334b0 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61  lled a a "virtua
334c0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
334d0 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
334e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
334f0 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
33500 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
33510 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
33520 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
33530 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
33540 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76  dule..**.** ^A v
33550 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33560 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
33570 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
33580 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
33590 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
335a0 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
335b0 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
335c0 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
335d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
335e0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
335f0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
33600 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
33610 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61  ** ^The registra
33620 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c  tion remains val
33630 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  id until it is r
33640 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66  eplaced by a dif
33650 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65  ferent.** module
33660 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64   or until the [d
33670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33680 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65  on] closes.  The
33690 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74   content.** of t
336a0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75  his structure mu
336b0 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68  st not change wh
336c0 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74  ile it is regist
336d0 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79  ered with.** any
336e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
336f0 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  tion..*/.struct 
33700 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
33710 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
33720 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
33730 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
33740 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
33750 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
33760 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
33770 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
33780 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
33790 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
337a0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
337b0 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
337c0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
337d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
337e0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
337f0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
33800 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33810 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
33820 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
33830 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
33840 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
33850 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
33860 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
33870 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
33880 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
33890 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
338a0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
338b0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
338c0 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
338d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
338e0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
338f0 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
33900 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
33910 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
33920 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
33930 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
33940 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
33950 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
33960 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
33970 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
33980 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
33990 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
339a0 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
339b0 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
339c0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
339d0 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
339e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
339f0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
33a00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
33a10 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
33a20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
33a30 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
33a40 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33a50 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
33a60 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
33a70 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
33a80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
33a90 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
33aa0 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
33ab0 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
33ac0 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
33ad0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
33ae0 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
33af0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
33b00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
33b10 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
33b20 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
33b30 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
33b40 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
33b50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
33b60 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
33b70 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
33b80 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
33b90 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
33ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33bb0 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
33bc0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
33bd0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33be0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
33bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33c00 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
33c10 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
33c20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
33c30 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
33c40 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
33c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
33c60 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
33c70 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
33c80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
33c90 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
33ca0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33cb0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
33cc0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
33cd0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
33ce0 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
33cf0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
33d00 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
33d10 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
33d20 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
33d30 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
33d40 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
33d50 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
33d60 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
33d70 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
33d80 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
33d90 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
33da0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
33db0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
33dc0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
33dd0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
33de0 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
33df0 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
33e00 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
33e10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
33e20 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
33e30 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
33e40 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
33e50 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
33e60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
33e70 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
33e80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
33e90 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
33ea0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
33eb0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
33ec0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
33ed0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
33ee0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
33ef0 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
33f00 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
33f10 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
33f20 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
33f30 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
33f40 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
33f50 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
33f60 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
33f70 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
33f80 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
33f90 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
33fa0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
33fb0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
33fc0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
33fd0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
33fe0 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
33ff0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
34000 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
34010 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
34020 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
34030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
34040 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
34050 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
34060 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
34070 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
34080 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
34090 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
340a0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
340b0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
340c0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
340d0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
340e0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
340f0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
34100 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
34110 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
34120 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
34130 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
34140 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
34150 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
34160 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
34170 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
34180 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
34190 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
341a0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
341b0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
341c0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
341d0 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
341e0 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
341f0 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
34200 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
34210 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
34220 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
34230 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
34240 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
34250 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
34260 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
34270 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
34280 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
34290 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
342a0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
342b0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
342c0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
342d0 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
342e0 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
342f0 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
34300 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
34310 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
34320 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
34330 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
34340 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
34350 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
34360 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
34370 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
34380 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
34390 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
343a0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
343b0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
343c0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
343d0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
343e0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
343f0 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
34400 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
34410 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
34420 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
34430 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
34440 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
34450 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
34460 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
34470 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
34480 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
34490 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
344a0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
344b0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
344c0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
344d0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
344e0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
344f0 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
34500 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
34510 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
34520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
34530 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
34540 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
34550 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
34560 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
34570 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
34580 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
34590 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
345a0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
345b0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
345c0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
345d0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
345e0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
345f0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
34600 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
34610 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
34620 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
34630 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
34640 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
34650 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
34660 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
34670 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
34680 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
34690 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
346a0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
346b0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
346c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
346d0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
346e0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
346f0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
34700 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
34710 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
34720 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
34730 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
34740 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
34750 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
34760 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
34770 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
34780 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
34790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
347a0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
347b0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
347c0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
347d0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
347e0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
347f0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
34800 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
34810 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
34820 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
34830 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
34840 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
34850 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
34860 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
34870 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
34880 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
34890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
348a0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
348b0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
348c0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
348d0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
348e0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
348f0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
34900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34910 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
34920 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
34930 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
34940 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
34950 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
34960 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
34970 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
34980 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
34990 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
349a0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
349b0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
349c0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
349d0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
349e0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
349f0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
34a00 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
34a10 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
34a20 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
34a30 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
34a40 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
34a50 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
34a60 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
34a70 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
34a80 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
34a90 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
34aa0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
34ab0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
34ac0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
34ad0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
34ae0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
34af0 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
34b00 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
34b10 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
34b20 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
34b30 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
34b40 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
34b50 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
34b60 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
34b70 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
34b80 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
34b90 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
34ba0 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70  le Constraint Op
34bb0 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a  erator Codes.**.
34bc0 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
34bd0 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f  defined the allo
34be0 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74  wed values for t
34bf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  he.** [sqlite3_i
34c00 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73  ndex_info].aCons
34c10 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
34c20 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72  d.  Each value r
34c30 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20  epresents.** an 
34c40 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73  operator that is
34c50 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74   part of a const
34c60 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68  raint term in th
34c70 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e wHERE clause o
34c80 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61  f.** a query tha
34c90 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61  t uses a [virtua
34ca0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65  l table]..*/.#de
34cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
34cc0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
34cd0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
34ce0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34cf0 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
34d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
34d10 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
34d20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
34d30 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34d40 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
34d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
34d60 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
34d70 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
34d80 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34d90 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
34da0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34db0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
34dc0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
34dd0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  entation.**.** ^
34de0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34df0 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
34e00 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
34e10 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
34e20 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
34e30 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
34e40 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
34e50 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
34e60 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
34e70 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
34e80 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
34e90 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
34ea0 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
34eb0 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
34ec0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
34ed0 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
34ee0 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
34ef0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34f00 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
34f10 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
34f20 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
34f30 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
34f40 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
34f50 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
34f60 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
34f70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
34f80 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
34f90 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
34fa0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
34fb0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
34fc0 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
34fd0 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
34fe0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
34ff0 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
35000 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
35010 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
35020 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
35030 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
35040 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
35050 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
35060 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
35070 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
35080 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
35090 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
350a0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
350b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
350c0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
350d0 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
350e0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
350f0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
35100 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
35110 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
35120 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
35130 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
35140 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
35150 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
35160 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
35170 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
35180 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
35190 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
351a0 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74  nter.  ^The dest
351b0 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f  ructor will also
351c0 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69  .** be invoked i
351d0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
351e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
351f0 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ule_v2() fails..
35200 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35210 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a  create_module().
35220 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
35230 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71  equivalent to sq
35240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
35250 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ule_v2() with a 
35260 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74  NULL.** destruct
35270 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
35280 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
35290 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
352a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
352b0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
352c0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
352d0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
352e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
352f0 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
35300 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
35310 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
35320 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
35330 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
35340 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
35350 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
35360 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta          /* C
35370 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
35380 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
35390 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
353a0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
353b0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
353c0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
353d0 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
353e0 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
353f0 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
35400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35410 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
35420 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
35430 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
35440 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
35450 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
35460 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
35470 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
35480 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a  Data,         /*
35490 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
354a0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
354b0 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
354c0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
354d0 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
354e0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
354f0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
35500 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
35510 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62  able Instance Ob
35520 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
35530 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
35540 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
35550 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
35560 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
35570 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
35580 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  .** of this obje
35590 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ct to describe a
355a0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
355b0 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
355c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
355d0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
355e0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
355f0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
35600 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
35610 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
35620 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
35630 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
35640 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
35650 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
35660 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
35670 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
35680 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
35690 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69  tions..**.** ^Vi
356a0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
356b0 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
356c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
356d0 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
356e0 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
356f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
35700 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72  rintf()] to zErr
35710 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
35720 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
35730 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
35740 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
35750 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
35760 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
35770 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ].** prior to as
35780 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
35790 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
357a0 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72    ^After the err
357b0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73  or message.** is
357c0 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f   delivered up to
357d0 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c   the client appl
357e0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72  ication, the str
357f0 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ing will be auto
35800 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65  matically.** fre
35810 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72  ed by sqlite3_fr
35820 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72  ee() and the zEr
35830 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20  rMsg field will 
35840 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74  be zeroed..*/.st
35850 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
35860 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69  b {.  const sqli
35870 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64  te3_module *pMod
35880 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64  ule;  /* The mod
35890 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72  ule for this vir
358a0 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20  tual table */.  
358b0 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20  int nRef;       
358c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
358d0 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45  /* NO LONGER USE
358e0 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  D */.  char *zEr
358f0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
35900 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
35910 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
35920 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
35930 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
35940 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
35950 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
35960 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
35970 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
35980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35990 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43   Virtual Table C
359a0 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20  ursor Object.** 
359b0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
359c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76  3_vtab_cursor {v
359d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
359e0 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  sor}.**.** Every
359f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
35a00 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
35a10 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
35a20 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
35a30 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
35a40 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65  ture to describe
35a50 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
35a60 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  int into the.** 
35a70 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
35a80 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
35a90 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
35aa0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
35ab0 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
35ac0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
35ad0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f  e.** [sqlite3_mo
35ae0 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70  dule.xOpen | xOp
35af0 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  en] method of th
35b00 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65  e module and are
35b10 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79   destroyed.** by
35b20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f   the [sqlite3_mo
35b30 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43  dule.xClose | xC
35b40 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43  lose] method.  C
35b50 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a  ursors are used.
35b60 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74  ** by the [xFilt
35b70 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78  er], [xNext], [x
35b80 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c  Eof], [xColumn],
35b90 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65   and [xRowid] me
35ba0 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20  thods.** of the 
35bb0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
35bc0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
35bd0 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
35be0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
35bf0 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
35c00 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
35c10 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
35c20 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
35c30 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
35c40 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
35c50 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
35c60 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
35c70 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
35c80 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
35c90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
35ca0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
35cb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
35cc0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
35cd0 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
35ce0 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
35cf0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
35d00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
35d10 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
35d20 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
35d30 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
35d40 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
35d50 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20  e The Schema Of 
35d60 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
35d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65  **.** ^The [xCre
35d80 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
35d90 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ct] methods of a
35da0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
35db0 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20  le module] call 
35dc0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a  this interface.*
35dd0 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
35de0 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
35df0 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
35e00 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
35e10 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
35e20 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
35e30 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  mplement..*/.int
35e40 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
35e50 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
35e60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
35e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35e80 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
35e90 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
35ea0 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a  rtual Table.**.*
35eb0 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c  * ^(Virtual tabl
35ec0 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
35ed0 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
35ee0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
35ef0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
35f00 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
35f10 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
35f20 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
35f30 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
35f40 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
35f50 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
35f60 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
35f70 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
35f80 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29   be overloaded.)
35f90 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41  ^.**.** ^(This A
35fa0 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
35fb0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
35fc0 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
35fd0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
35fe0 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
35ff0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
36000 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
36010 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
36020 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
36030 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
36040 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
36050 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20   is created.)^  
36060 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
36070 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
36080 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
36090 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
360a0 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
360b0 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
360c0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
360d0 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
360e0 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
360f0 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
36100 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
36110 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
36120 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
36130 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
36140 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
36150 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  le]..*/.int sqli
36160 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
36170 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
36180 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
36190 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
361a0 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
361b0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
361c0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
361d0 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
361e0 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
361f0 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
36200 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
36210 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
36220 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
36230 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
36240 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
36250 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
36260 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
36270 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
36280 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
36290 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
362a0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
362b0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
362c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
362d0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
362e0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
362f0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
36300 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
36310 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
36320 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
36330 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
36340 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
36350 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t..*/../*.** CAP
36360 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
36370 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  To An Open BLOB.
36380 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c  ** KEYWORDS: {BL
36390 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42  OB handle} {BLOB
363a0 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20   handles}.**.** 
363b0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
363c0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
363d0 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
363e0 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b  OB on which.** [
363f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
36400 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
36410 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65  BLOB I/O] can be
36420 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e   performed..** ^
36430 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20  Objects of this 
36440 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64  type are created
36450 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
36460 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  b_open()].** and
36470 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
36480 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
36490 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  e()]..** ^The [s
364a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
364b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
364c0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
364d0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
364e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
364f0 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
36500 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
36510 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65  he BLOB..** ^The
36520 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
36530 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
36540 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
36550 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69  ze of the BLOB i
36560 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
36570 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36580 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
36590 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
365a0 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
365b0 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
365c0 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54  al I/O.**.** ^(T
365d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f  his interfaces o
365e0 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e  pens a [BLOB han
365f0 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f  dle | handle] to
36600 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65   the BLOB locate
36610 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77  d.** in row iRow
36620 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
36630 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  , table zTable i
36640 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a  n database zDb;.
36650 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** in other word
36660 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42  s, the same BLOB
36670 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73   that would be s
36680 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
36690 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
366a0 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
366b0 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
366c0 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52  ERE [rowid] = iR
366d0 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  ow;.** </pre>)^.
366e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c  **.** ^If the fl
366f0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
36700 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
36710 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
36720 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61  ed for read.** a
36730 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
36740 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c   ^If it is zero,
36750 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
36760 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63  ned for read acc
36770 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e  ess..** ^It is n
36780 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
36790 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
367a0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20  t is part of an 
367b0 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79  index or primary
367c0 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69   .** key for wri
367d0 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69  ting. ^If [forei
367e0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
367f0 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c  ts] are enabled,
36800 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70   it is .** not p
36810 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
36820 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
36830 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c   part of a [chil
36840 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69  d key] for writi
36850 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  ng..**.** ^Note 
36860 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
36870 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68  e name is not th
36880 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  e filename that 
36890 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
368a0 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74  database but rat
368b0 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63  her the symbolic
368c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
368d0 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70  abase that.** ap
368e0 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20  pears after the 
368f0 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20  AS keyword when 
36900 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
36910 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20  connected using 
36920 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f  [ATTACH]..** ^Fo
36930 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
36940 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61  ase file, the da
36950 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
36960 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54  main"..** ^For T
36970 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
36980 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
36990 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e   "temp"..**.** ^
369a0 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51  (On success, [SQ
369b0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
369c0 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
369d0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
369e0 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
369f0 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
36a00 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
36a10 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
36a20 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
36a30 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
36a40 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20  l pointer.)^.** 
36a50 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73  ^This function s
36a60 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
36a70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
36a80 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
36a90 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
36aa0 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
36ab0 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
36ac0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
36ad0 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
36ae0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74   functions. ^Not
36af0 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
36b00 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
36b10 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
36b20 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
36b30 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
36b40 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
36b50 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
36b60 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
36b70 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
36b80 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
36b90 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
36ba0 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  tine..**.** ^(If
36bb0 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20   the row that a 
36bc0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e  BLOB handle poin
36bd0 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65  ts to is modifie
36be0 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41  d by an.** [UPDA
36bf0 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f  TE], [DELETE], o
36c00 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  r by [ON CONFLIC
36c10 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a  T] side-effects.
36c20 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  ** then the BLOB
36c30 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65   handle is marke
36c40 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a  d as "expired"..
36c50 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20  ** This is true 
36c60 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66  if any column of
36c70 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e   the row is chan
36c80 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75  ged, even a colu
36c90 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  mn.** other than
36ca0 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f   the one the BLO
36cb0 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  B handle is open
36cc0 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73   on.)^.** ^Calls
36cd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
36ce0 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
36cf0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
36d00 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
36d10 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
36d20 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
36d30 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
36d40 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
36d50 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74   ^(Changes writt
36d60 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70  en into a BLOB p
36d70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42  rior to the BLOB
36d80 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f   expiring are no
36d90 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t.** rolled back
36da0 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
36db0 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
36dc0 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
36dd0 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
36de0 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
36df0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
36e00 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
36e10 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65  on.)^.**.** ^Use
36e20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
36e30 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
36e40 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69  rface to determi
36e50 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ne the size of.*
36e60 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f  * the opened blo
36e70 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  b.  ^The size of
36e80 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20   a blob may not 
36e90 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68  be changed by th
36ea0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  is.** interface.
36eb0 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54    Use the [UPDAT
36ec0 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  E] SQL command t
36ed0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  o change the siz
36ee0 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a  e of a.** blob..
36ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36f00 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
36f10 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  b()] and [sqlite
36f20 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
36f30 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  b()] interfaces.
36f40 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74  ** and the built
36f50 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53  -in [zeroblob] S
36f60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  QL function can 
36f70 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69  be used, if desi
36f80 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74  red,.** to creat
36f90 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f  e an empty, zero
36fa0 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20  -filled blob in 
36fb0 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72  which to read or
36fc0 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20   write using.** 
36fd0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
36fe0 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61  **.** To avoid a
36ff0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20   resource leak, 
37000 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42  every open [BLOB
37010 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20   handle] should 
37020 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65  eventually.** be
37030 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63   released by a c
37040 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37050 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
37060 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
37070 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
37080 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
37090 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
370a0 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
370b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
370c0 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
370d0 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
370e0 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
370f0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
37100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37110 45 46 3a 20 4d 6f 76 65 20 61 20 42 4c 4f 42 20  EF: Move a BLOB 
37120 48 61 6e 64 6c 65 20 74 6f 20 61 20 4e 65 77 20  Handle to a New 
37130 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  Row.**.** ^This 
37140 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
37150 20 74 6f 20 6d 6f 76 65 20 61 6e 20 65 78 69 73   to move an exis
37160 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ting blob handle
37170 20 73 6f 20 74 68 61 74 20 69 74 20 70 6f 69 6e   so that it poin
37180 74 73 0a 2a 2a 20 74 6f 20 61 20 64 69 66 66 65  ts.** to a diffe
37190 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
371a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 74 61  same database ta
371b0 62 6c 65 2e 20 5e 54 68 65 20 6e 65 77 20 72 6f  ble. ^The new ro
371c0 77 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 0a  w is identified.
371d0 2a 2a 20 62 79 20 74 68 65 20 72 6f 77 69 64 20  ** by the rowid 
371e0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
371f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
37200 65 6e 74 2e 20 4f 6e 6c 79 20 74 68 65 20 72 6f  ent. Only the ro
37210 77 20 63 61 6e 20 62 65 0a 2a 2a 20 63 68 61 6e  w can be.** chan
37220 67 65 64 2e 20 5e 54 68 65 20 64 61 74 61 62 61  ged. ^The databa
37230 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
37240 6c 75 6d 6e 20 6f 6e 20 77 68 69 63 68 20 74 68  lumn on which th
37250 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73  e blob handle is
37260 20 6f 70 65 6e 0a 2a 2a 20 72 65 6d 61 69 6e 20   open.** remain 
37270 74 68 65 20 73 61 6d 65 2e 20 4d 6f 76 69 6e 67  the same. Moving
37280 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f   an existing blo
37290 62 20 68 61 6e 64 6c 65 20 74 6f 20 61 20 6e 65  b handle to a ne
372a0 77 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20  w row can be.** 
372b0 66 61 73 74 65 72 20 74 68 61 6e 20 63 6c 6f 73  faster than clos
372c0 69 6e 67 20 74 68 65 20 65 78 69 73 74 69 6e 67  ing the existing
372d0 20 68 61 6e 64 6c 65 20 61 6e 64 20 6f 70 65 6e   handle and open
372e0 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 2e 0a 2a  ing a new one..*
372f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 6e 65 77 20 72  *.** ^(The new r
37300 6f 77 20 6d 75 73 74 20 6d 65 65 74 20 74 68 65  ow must meet the
37310 20 73 61 6d 65 20 63 72 69 74 65 72 69 61 20 61   same criteria a
37320 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  s for [sqlite3_b
37330 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a 2a 2a  lob_open()] -.**
37340 20 69 74 20 6d 75 73 74 20 65 78 69 73 74 20 61   it must exist a
37350 6e 64 20 74 68 65 72 65 20 6d 75 73 74 20 62 65  nd there must be
37360 20 65 69 74 68 65 72 20 61 20 62 6c 6f 62 20 6f   either a blob o
37370 72 20 74 65 78 74 20 76 61 6c 75 65 20 73 74 6f  r text value sto
37380 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 6f  red in.** the no
37390 6d 69 6e 61 74 65 64 20 63 6f 6c 75 6d 6e 2e 29  minated column.)
373a0 5e 20 5e 49 66 20 74 68 65 20 6e 65 77 20 72 6f  ^ ^If the new ro
373b0 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74  w is not present
373c0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c 20 6f   in the table, o
373d0 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  r if.** it does 
373e0 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20 62 6c  not contain a bl
373f0 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65  ob or text value
37400 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65 72 20  , or if another 
37410 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 61 6e  error occurs, an
37420 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72 6f 72  .** SQLite error
37430 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
37440 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62 20 68  d and the blob h
37450 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69 64 65  andle is conside
37460 72 65 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a 20  red aborted..** 
37470 5e 41 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20  ^All subsequent 
37480 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
37490 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c 20  3_blob_read()], 
374a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
374b0 69 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ite()] or.** [sq
374c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65  lite3_blob_reope
374d0 6e 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74  n()] on an abort
374e0 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69  ed blob handle i
374f0 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
37500 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f 52  n.** SQLITE_ABOR
37510 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  T..**.** ^This f
37520 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
37530 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
37540 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
37550 6d 65 73 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49  message..*/.SQLI
37560 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
37570 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
37580 5f 72 65 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f  _reopen(sqlite3_
37590 62 6c 6f 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f  blob *, sqlite3_
375a0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
375b0 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41  API3REF: Close A
375c0 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
375d0 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70  ** ^Closes an op
375e0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
375f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67  ..**.** ^Closing
37600 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61   a BLOB shall ca
37610 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  use the current 
37620 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63  transaction to c
37630 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72  ommit.** if ther
37640 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42  e are no other B
37650 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67  LOBs, no pending
37660 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37670 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  ents, and the.**
37680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37690 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f  tion is in [auto
376a0 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a  commit mode]..**
376b0 20 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20   ^If any writes 
376c0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
376d0 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
376e0 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
376f0 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
37700 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
37710 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
37720 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e  ..**.** ^(Closin
37730 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
37740 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
37750 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
37760 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
37770 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
37780 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
37790 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
377a0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
377b0 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
377c0 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68  .  Any errors th
377d0 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a  at occur during.
377e0 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72  ** closing are r
377f0 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e  eported as a non
37800 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c  -zero return val
37810 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ue.)^.**.** ^(Th
37820 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
37830 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
37840 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20  .  Even if this 
37850 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a  routine returns.
37860 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  ** an error code
37870 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74  , the BLOB is st
37880 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a  ill closed.)^.**
37890 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
378a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
378b0 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73   null pointer (s
378c0 75 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20  uch as would be 
378d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61  returned.** by a
378e0 20 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20   failed call to 
378f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
37900 65 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d  en()]) is a harm
37910 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
37920 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
37930 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
37940 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
37950 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
37960 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
37970 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52  en BLOB.**.** ^R
37980 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
37990 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
379a0 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20  BLOB accessible 
379b0 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63  via the .** succ
379c0 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20  essfully opened 
379d0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
379e0 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
379f0 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63  nt.  ^The.** inc
37a00 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f  remental blob I/
37a10 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f  O routines can o
37a20 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72  nly read or over
37a30 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67  writing existing
37a40 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74  .** blob content
37a50 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68  ; they cannot ch
37a60 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
37a70 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54   a blob..**.** T
37a80 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
37a90 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
37aa0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
37ab0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
37ac0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
37ad0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37ae0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
37af0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
37b00 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
37b10 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
37b20 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
37b30 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
37b40 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
37b50 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
37b60 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
37b70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
37b80 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
37b90 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a  le behavior..*/.
37ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
37bb0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
37bc0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
37bd0 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
37be0 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
37bf0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
37c00 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
37c10 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
37c20 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
37c30 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
37c40 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
37c50 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
37c60 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
37c70 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
37c80 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
37c90 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
37ca0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
37cb0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
37cc0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66  )^.**.** ^If off
37cd0 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
37ce0 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
37cf0 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
37d00 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
37d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
37d20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
37d30 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e  data is read.  ^
37d40 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20  If N or iOffset 
37d50 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
37d60 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52  zero, [SQLITE_ER
37d70 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
37d80 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
37d90 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69  read..** ^The si
37da0 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28  ze of the blob (
37db0 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
37dc0 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
37dd0 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
37de0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
37df0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
37e00 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
37e10 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
37e20 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20   ^An attempt to 
37e30 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70  read from an exp
37e40 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
37e50 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
37e60 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
37e70 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
37e80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
37e90 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
37ea0 6f 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e  ob_read() return
37eb0 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
37ec0 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65  Otherwise, an [e
37ed0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
37ee0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
37ef0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
37f00 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ed.)^.**.** This
37f10 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
37f20 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
37f30 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
37f40 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
37f50 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
37f60 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
37f70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
37f80 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
37f90 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
37fa0 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
37fb0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
37fc0 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
37fd0 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
37fe0 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
37ff0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
38000 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
38010 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
38020 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
38030 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
38040 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
38050 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
38060 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74  _blob_read(sqlit
38070 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20  e3_blob *, void 
38080 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69  *Z, int N, int i
38090 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
380a0 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20  CAPI3REF: Write 
380b0 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42  Data Into A BLOB
380c0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a   Incrementally.*
380d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
380e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77  ion is used to w
380f0 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61  rite data into a
38100 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
38110 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63  dle] from a.** c
38120 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62  aller-supplied b
38130 75 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20  uffer. ^N bytes 
38140 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
38150 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66  ed from the buff
38160 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  er Z.** into the
38170 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72   open BLOB, star
38180 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
38190 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  Offset..**.** ^I
381a0 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  f the [BLOB hand
381b0 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  le] passed as th
381c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
381d0 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
381e0 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28  for.** writing (
381f0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
38200 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
38210 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73  blob_open()] was
38220 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20   zero),.** this 
38230 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
38240 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   [SQLITE_READONL
38250 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  Y]..**.** ^This 
38260 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c  function may onl
38270 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e  y modify the con
38280 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f  tents of the BLO
38290 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  B; it is.** not 
382a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72  possible to incr
382b0 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ease the size of
382c0 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68   a BLOB using th
382d0 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f  is API..** ^If o
382e0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
382f0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74   less than N byt
38300 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
38310 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20  of the BLOB,.** 
38320 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
38330 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
38340 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65  o data is writte
38350 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20  n.  ^If N is.** 
38360 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
38370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
38380 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
38390 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
383a0 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
383b0 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68   the BLOB (and h
383c0 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
383d0 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
383e0 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
383f0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
38400 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
38410 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
38420 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
38430 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  attempt to write
38440 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b   to an expired [
38450 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
38460 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
38470 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
38480 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72  ITE_ABORT].  ^Wr
38490 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42  ites to the BLOB
384a0 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a   that occurred.*
384b0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c  * before the [BL
384c0 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72  OB handle] expir
384d0 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65  ed are not rolle
384e0 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a  d back by the.**
384f0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
38500 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67  he handle, thoug
38510 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73  h of course thos
38520 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a  e changes might.
38530 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65  ** have been ove
38540 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
38550 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65  statement that e
38560 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20  xpired the BLOB 
38570 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20  handle.** or by 
38580 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e  other independen
38590 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  t statements..**
385a0 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
385b0 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  , sqlite3_blob_w
385c0 72 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53  rite() returns S
385d0 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68  QLITE_OK..** Oth
385e0 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
385f0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
38600 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
38610 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
38620 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
38630 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
38640 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
38650 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
38660 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
38670 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
38680 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
38690 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
386a0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
386b0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
386c0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
386d0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
386e0 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
386f0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
38700 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
38710 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
38720 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
38730 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
38740 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
38750 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
38760 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a  _blob_read()]..*
38770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
38780 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33  ob_write(sqlite3
38790 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76  _blob *, const v
387a0 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69  oid *z, int n, i
387b0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
387c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
387d0 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
387e0 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
387f0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
38800 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
38810 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
38820 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
38830 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
38840 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
38850 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
38860 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
38870 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c  Most SQLite buil
38880 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
38890 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
388a0 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
388b0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
388c0 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
388d0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
388e0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
388f0 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
38900 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73