/ Hex Artifact Content
Login

Artifact da5f52960e61bd8940413bd07da0e8150531552d:


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 2a 0a   of fsync()..**.
6040: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6050: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6060: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6070: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6080: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6090: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60a0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
60b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60c0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
60d0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
60e0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
60f0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6100: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6110: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6120: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6130: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6140: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6150: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6170: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6180: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6190: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
61a0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
61b0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
61c0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
61d0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
61e0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
61f0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6200: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6210: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6220: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6240: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6250: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6260: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6270: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6290: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
62a0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
62b0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
62c0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
62d0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
62e0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
62f0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6320: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6340: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6350: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6370: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
63a0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
63b0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
63c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
63d0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
63e0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
63f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
6400: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
6410: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
6420: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
6430: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6440: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6450: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6460: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6470: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6480: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6490: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
64a0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
64b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
64c0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
64d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
64e0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
64f0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
6500: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
6510: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
6520: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
6530: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6540: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
6550: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
6570: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
6590: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
65a0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
65b0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
65c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
65d0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
65e0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
65f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
6600: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
6610: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
6620: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
6630: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
6640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6650: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
6660: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
6670: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
6680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6690: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
66a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
66b0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
66c0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
66d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
66e0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
66f0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
6700: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
6710: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
6720: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
6730: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6740: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
6750: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e  .** If the xOpen
6760: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6770: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6780: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6790: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
67a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
67b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
67c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
67d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
67e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
67f0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64  e xOpen reported
6800: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6810: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6820: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6830: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6840: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72   xOpen.** is for
6860: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65   the xOpen to se
6870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
6880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
6890: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ent to NULL..**.
68a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
68b0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
68c0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
68e0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
68f0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
6900: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
6910: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
6920: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
6930: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6940: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6950: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6960: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6970: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6980: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6990: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
69a0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
69b0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
69c0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
69d0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
69e0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
69f0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
6a00: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6a10: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
6a20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6a30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6a50: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a70: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6ab0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
6ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
6ad0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
6ae0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
6af0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
6b00: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
6b10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6b20: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
6b30: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6b40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6b50: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6b60: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6b70: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6b80: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6b90: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6ba0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6bb0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
6bc0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
6bd0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
6be0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
6bf0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
6c00: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
6c10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
6c20: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6c30: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6c40: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6c50: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6c60: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6c70: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6c80: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6c90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6ca0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6cb0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6cc0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6cd0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
6ce0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
6cf0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
6d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
6d10: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
6d20: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
6d30: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6d40: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6d50: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6d60: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6d70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6d80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6d90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6da0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6db0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
6dc0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
6dd0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
6de0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
6df0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
6e00: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
6e10: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
6e20: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
6e30: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6e40: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6e50: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6e60: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6e70: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6e80: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6e90: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6ea0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6eb0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
6ec0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6ed0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6ee0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6ef0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6f00: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6f10: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6f20: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6f30: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6f40: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6f50: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6f60: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6f70: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6f80: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6f90: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6fa0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6fb0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
6fc0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
6fd0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
6fe0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
6ff0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7000: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7010: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7020: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7030: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7040: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7060: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7070: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7080: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7090: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
70a0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
70b0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
70c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7130: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7150: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7170: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7190: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
71a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
71b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
71c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
71d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
71e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7200: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7210: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7220: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7230: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7240: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7250: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7260: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7270: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7280: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7290: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
72a0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
72b0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
72c0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
72d0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
72e0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
72f0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7300: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7310: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7320: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7330: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7350: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7360: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7380: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7390: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
73a0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
73c0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
73d0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
73e0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
73f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
7410: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
7420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
7430: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7440: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7450: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7460: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
7470: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
7480: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
7490: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
74a0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
74b0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
74c0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
74d0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
74e0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
74f0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
7500: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
7510: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
7520: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
7530: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
7540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
7550: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
7560: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
7570: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
7580: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7590: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
75a0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
75b0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
75c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75d0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
75e0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
75f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
7600: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7610: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
7620: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
7630: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7640: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7650: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7660: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
7670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
76a0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
76b0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
76c0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
76d0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
76e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
76f0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7700: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7720: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
7730: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7750: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7760: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
7770: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7780: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
7790: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
77a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
77b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
77c0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
77d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
77e0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
77f0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
7800: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
7820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7830: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7840: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
7850: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7860: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
7870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
7880: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
7890: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
78a0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
78b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
78c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
78d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
78e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
78f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
7900: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
7910: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
7920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
7930: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
7940: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
7950: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
7960: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7970: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
7980: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
7990: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
79a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
79b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
79c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
79d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
79e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
79f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
7a00: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
7a10: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
7a20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7a30: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
7a40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
7a60: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7a80: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
7a90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ab0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7ac0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
7ad0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
7ae0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
7af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7b00: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
7b10: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
7b20: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
7b40: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
7b50: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
7b60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7b70: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
7b80: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ba0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
7bb0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
7bc0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
7bd0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
7be0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
7bf0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
7c00: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
7c10: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
7c20: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
7c30: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
7c40: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
7c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
7c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
7c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
7ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
7cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
7cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
7cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
7ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
7cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
7d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
7d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
7d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
7d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
7d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
7d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
7d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
7d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
7d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
7d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
7da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
7db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
7dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
7de0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
7df0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
7e00: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
7e10: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
7e20: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
7e30: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
7e40: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
7e50: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
7e60: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
7e70: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
7e80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7ea0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
7eb0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
7ec0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
7ed0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
7ee0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
7ef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
7f00: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
7f10: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
7f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
7f30: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
7f40: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
7f50: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
7f60: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
7f70: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
7f80: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
7f90: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
7fa0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
7fb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7fc0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
7fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7fe0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
7ff0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8010: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8020: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8030: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8040: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8060: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8070: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8080: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8090: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
80a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
80b0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
80c0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
80d0: 2e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 0a 2a  . SQLite calls.*
80e0: 2a 20 74 68 65 20 66 69 6c 65 2d 63 6f 6e 74 72  * the file-contr
80f0: 6f 6c 20 6d 65 74 68 6f 64 20 77 69 74 68 20 74  ol method with t
8100: 68 69 73 20 6f 70 63 6f 64 65 20 69 6d 6d 65 64  his opcode immed
8110: 69 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65  iately after the
8120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8130: 65 20 69 73 20 73 79 6e 63 65 64 2c 20 6f 72 20  e is synced, or 
8140: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
8150: 69 73 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 79  is running in sy
8160: 6e 63 68 72 6f 6e 6f 75 73 3d 6f 66 66 20 6d 6f  nchronous=off mo
8170: 64 65 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  de.** immediatel
8180: 79 20 61 66 74 65 72 20 69 74 20 77 6f 75 6c 64  y after it would
8190: 20 68 61 76 65 20 62 65 65 6e 20 73 79 6e 63 65   have been synce
81a0: 64 20 6f 74 68 65 72 77 69 73 65 2e 20 54 68 69  d otherwise. Thi
81b0: 73 20 6d 61 6b 65 73 20 69 74 0a 2a 2a 20 65 61  s makes it.** ea
81c0: 73 69 65 72 20 74 6f 20 77 72 69 74 65 20 73 70  sier to write sp
81d0: 65 63 69 61 6c 20 56 46 53 20 6d 6f 64 75 6c 65  ecial VFS module
81e0: 73 20 74 68 61 74 20 64 65 70 65 6e 64 20 6f 6e  s that depend on
81f0: 20 74 68 65 20 78 53 79 6e 63 20 63 61 6c 6c 2e   the xSync call.
8200: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8210: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8220: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
8230: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
8240: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8250: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
8260: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
8270: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
8280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
8290: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
82a0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
82b0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
82c0: 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66  NT        5.#def
82d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
82e0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
82f0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
8300: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8310: 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66  INTER     7.#def
8320: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8330: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
8340: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
8350: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
8360: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
8370: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
8380: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
8390: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
83a0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
83b0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
83c0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
83d0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
83e0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
83f0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
8400: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
8410: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
8420: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
8430: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
8440: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
8450: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
8460: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
8470: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
8480: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
8490: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
84a0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
84b0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
84c0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
84d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
84e0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
84f0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
8500: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
8510: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
8520: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
8530: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
8540: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
8550: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
8560: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
8570: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
8580: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
8590: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
85a0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
85b0: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
85c0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
85d0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
85e0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
85f0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
8600: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
8610: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
8620: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
8630: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
8640: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
8650: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
8660: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
8670: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
8680: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
8690: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
86a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
86b0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
86c0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
86d0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
86e0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
86f0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
8700: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
8710: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
8720: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
8730: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
8740: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
8750: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
8760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
8770: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
8780: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
8790: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
87a0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
87b0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
87c0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
87d0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
87e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
87f0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
8800: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
8810: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
8820: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
8830: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
8840: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
8850: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
8860: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
8870: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
8880: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
8890: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
88a0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
88b0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
88c0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
88d0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
88e0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
88f0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
8900: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
8910: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
8920: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
8930: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
8940: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
8950: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
8960: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
8970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
8980: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
8990: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
89a0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
89b0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
89c0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
89d0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
89e0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
89f0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
8a00: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
8a10: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
8a20: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
8a30: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
8a40: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
8a50: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
8a60: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
8a70: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
8a80: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
8a90: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
8aa0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
8ab0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
8ac0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
8ad0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  modules..**.** ^
8ae0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
8af0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
8b00: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8b10: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
8b20: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
8b30: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
8b40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
8b50: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
8b60: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
8b70: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
8b80: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
8b90: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
8ba0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8bb0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
8bc0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
8bd0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
8be0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
8bf0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61  ore than.** 10 a
8c00: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
8c10: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
8c20: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
8c30: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
8c40: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
8c50: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
8c60: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
8c70: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
8c80: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
8c90: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
8ca0: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
8cb0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8cc0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8cd0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
8ce0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
8cf0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
8d00: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
8d10: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
8d20: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
8d30: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8d40: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
8d50: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8d60: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8d70: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
8d80: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8d90: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8da0: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
8db0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8dc0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8dd0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8de0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8df0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8e00: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8e10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8e20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8e30: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8e40: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8e50: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8e60: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8e70: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8e80: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8e90: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8eb0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8ec0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8ed0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8ee0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8ef0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8f00: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8f20: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8f30: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8f40: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8f50: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8f60: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8f70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8f80: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8f90: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8fa0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8fb0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
8fc0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8fd0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8fe0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8ff0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
9000: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
9010: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
9020: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
9030: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9040: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
9050: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9060: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
9070: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
9090: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
90a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
90b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
90c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
90d0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
90e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
90f0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
9100: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9110: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
9120: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9130: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
9140: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
9150: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
9160: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
9170: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
9180: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
9190: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
91a0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
91b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
91c0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
91d0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
91e0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
91f0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
9200: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
9210: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
9220: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
9230: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
9240: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
9250: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
9260: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
9270: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
9280: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
9290: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
92a0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
92b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
92c0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
92d0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
92e0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
92f0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
9300: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
9310: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
9320: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
9330: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
9340: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
9350: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
9360: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
9370: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
9380: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
9390: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
93a0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
93b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
93c0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
93d0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
93e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
93f0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
9400: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
9410: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
9420: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
9430: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
9440: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
9450: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
9460: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
9470: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9480: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
9490: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
94a0: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
94b0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
94c0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
94d0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
94e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
94f0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
9500: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
9510: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
9520: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
9530: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
9540: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
9550: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
9560: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
9570: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
9580: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
9590: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
95a0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
95b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
95c0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
95d0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
95e0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
95f0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
9600: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9610: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
9620: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
9630: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
9640: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
9650: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
9660: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
9670: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
9680: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
9690: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
96a0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
96b0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
96c0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
96d0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
96e0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
96f0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
9700: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
9710: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9720: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
9730: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
9740: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
9750: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
9760: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
9770: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
9780: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
9790: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
97a0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
97b0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
97c0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
97d0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
97e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
97f0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
9800: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
9810: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
9820: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
9830: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
9840: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
9850: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
9860: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
9870: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
9880: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
9890: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
98a0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
98b0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
98c0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
98d0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
98e0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
98f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ..**.** ^The fla
9900: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9910: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9920: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
9930: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
9940: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
9950: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
9960: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
9970: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
9980: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9990: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
99a0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
99b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
99c0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
99d0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
99e0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
99f0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9a00: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9a10: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9a20: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
9a30: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
9a40: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
9a50: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
9a60: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
9a70: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
9a80: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9a90: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9aa0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9ab0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9ac0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9ad0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9af0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9b00: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9b10: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9b20: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
9b30: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
9b40: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
9b50: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
9b60: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9b70: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9b80: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9b90: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9ba0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9bb0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9bc0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9bd0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9be0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9bf0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9c00: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9c10: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
9c20: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
9c30: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9c40: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9c50: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9c60: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9c70: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9c80: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9c90: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9ca0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9cb0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9cc0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9cd0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
9ce0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
9cf0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
9d00: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9d10: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9d20: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9d30: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9d40: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9d50: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9d60: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9d70: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9d80: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9d90: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9da0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9db0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9dc0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
9dd0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
9de0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
9df0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
9e00: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
9e10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
9e20: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
9e30: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9e40: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
9e50: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
9e60: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9e70: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9e80: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9e90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9ea0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9eb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9ec0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9ed0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9ee0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9ef0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9f00: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
9f10: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
9f20: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
9f30: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
9f40: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
9f50: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
9f60: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9f70: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9f80: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9f90: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9fa0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9fb0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9fc0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9fd0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9fe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9ff0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
a000: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
a010: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
a020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
a030: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
a040: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
a050: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
a060: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
a070: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
a080: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
a090: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
a0a0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
a0b0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
a0c0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
a0d0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
a0e0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
a0f0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
a100: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
a110: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
a120: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
a130: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
a140: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
a150: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
a160: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
a170: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
a180: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a190: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a1a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a1b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a1c0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a1d0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a1e0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a1f0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a200: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a210: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a220: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a230: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a240: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a250: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a260: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a270: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a280: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a290: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a2a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a2b0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a2c0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a2d0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a2e0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a2f0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a300: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a310: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a320: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a330: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a340: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a350: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a360: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a370: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a380: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a390: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a3a0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a3b0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a3c0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a3d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a3e0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a3f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a400: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a410: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a420: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a430: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a440: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a450: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a460: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a470: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a480: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
a490: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a4a0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a4b0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
a4c0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
a4d0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
a4e0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
a4f0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
a500: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
a510: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
a520: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
a530: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
a540: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
a550: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a560: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a570: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
a580: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
a590: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
a5a0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
a5b0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
a5c0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
a5d0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
a5e0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
a5f0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
a600: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
a610: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
a620: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a630: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
a640: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
a650: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a660: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a670: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a680: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a690: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a6a0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a6b0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a6c0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a6d0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a6e0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a6f0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a700: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a710: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a720: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a730: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a740: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a750: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a760: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a770: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a780: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a790: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a7a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a7b0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a7c0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a7d0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a7e0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a7f0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a800: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a810: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a820: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a830: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a840: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a850: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a860: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a870: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a880: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a890: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a8a0: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a8b0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a8c0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a8d0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a8e0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a8f0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a900: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a910: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a930: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a940: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a950: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a960: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a970: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a980: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a990: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a9a0: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a9b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a9c0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a9e0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a9f0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
aa00: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
aa10: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
aa30: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
aa40: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
aa50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
aa60: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
aa70: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
aa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
aa90: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
aaa0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
aab0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
aac0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
aad0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
aae0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
aaf0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
ab00: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
ab10: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
ab20: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
ab30: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
ab40: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
ab50: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
ab60: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ab70: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
ab80: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
ab90: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aba0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
abb0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
abc0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
abd0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
abe0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
abf0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
ac00: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
ac10: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
ac20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
ac30: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
ac40: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
ac50: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
ac60: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
ac70: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
ac80: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
ac90: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
aca0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
acb0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
acc0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
acd0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
ace0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
acf0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ad00: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ad10: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ad20: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
ad30: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
ad40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ad50: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
ad60: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
ad70: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
ad80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ad90: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ada0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
adb0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
adc0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
add0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
ade0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
adf0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
ae00: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
ae10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ae20: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
ae30: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
ae40: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
ae50: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
ae60: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
ae70: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
ae80: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ae90: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
aea0: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
aeb0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
aec0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
aed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
aee0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
aef0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
af00: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
af10: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
af20: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
af30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af40: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
af50: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
af60: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
af70: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
af80: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
af90: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
afa0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
afb0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
afc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
afd0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
afe0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
aff0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
b000: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
b010: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
b020: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
b030: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
b040: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
b050: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
b060: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
b070: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
b080: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
b090: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
b0a0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
b0b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b0c0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
b0d0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
b0e0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
b0f0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
b100: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
b110: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
b120: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
b130: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
b140: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
b150: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
b160: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b170: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
b180: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
b190: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b1a0: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
b1b0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
b1c0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
b1d0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
b1e0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
b1f0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
b200: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
b210: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
b220: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
b230: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
b240: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
b250: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
b260: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
b270: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
b280: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
b290: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
b2a0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
b2b0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
b2c0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
b2d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
b2e0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
b2f0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
b300: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
b310: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
b320: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
b330: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
b340: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b350: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b360: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
b370: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
b380: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
b390: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
b3a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b3b0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
b3c0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
b3d0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
b3e0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
b3f0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
b400: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
b410: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
b420: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
b430: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
b440: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
b450: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
b460: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
b470: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
b480: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
b490: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
b4a0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
b4b0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
b4c0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
b4d0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
b4e0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
b4f0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
b500: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
b510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
b520: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
b530: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
b540: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
b550: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
b560: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
b570: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b580: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
b590: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
b5a0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
b5b0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
b5c0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
b5d0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
b5e0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
b5f0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
b600: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
b610: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b620: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b630: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b640: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
b650: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
b660: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b670: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b680: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b690: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b6a0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b6b0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b6c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b6d0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b6e0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b6f0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b700: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b710: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b720: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b730: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b740: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b750: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b760: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b770: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b780: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b790: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b7a0: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b7b0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b7c0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b7d0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b7e0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b7f0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b800: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b810: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b820: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b830: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b840: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b850: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b860: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b870: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b880: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b890: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b8a0: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b8b0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b8c0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b8d0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b8e0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b8f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b900: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b910: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b920: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b930: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b940: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b950: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b960: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b970: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b980: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b990: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b9a0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b9b0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b9c0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b9d0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b9e0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b9f0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
ba00: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ba10: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ba20: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
ba30: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
ba40: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
ba50: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
ba60: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
ba70: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
ba80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ba90: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
baa0: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
bab0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
bac0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
bad0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
bae0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
baf0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
bb00: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
bb10: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
bb20: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
bb30: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
bb40: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
bb50: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
bb60: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
bb70: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
bb80: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
bb90: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
bba0: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
bbb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bbc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
bbd0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
bbe0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
bbf0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
bc00: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
bc10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
bc20: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
bc30: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
bc40: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
bc50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bc60: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
bc70: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
bc80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bc90: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
bca0: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
bcb0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
bcc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
bcd0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
bce0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
bcf0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
bd00: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
bd10: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
bd20: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
bd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
bd40: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
bd50: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
bd60: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
bd70: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
bd80: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
bd90: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
bda0: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
bdb0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
bdc0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
bdd0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
bde0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
bdf0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
be00: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
be10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
be20: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
be30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
be40: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
be50: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
be60: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
be70: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
be80: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
be90: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
bea0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
beb0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
bec0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
bed0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
bee0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
bef0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
bf00: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
bf10: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
bf20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bf30: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
bf40: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
bf50: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
bf60: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
bf70: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
bf80: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
bf90: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
bfa0: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
bfb0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
bfc0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bfd0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bfe0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
bff0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
c000: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
c010: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
c020: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
c030: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
c040: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
c050: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
c060: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
c070: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
c080: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
c090: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
c0a0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
c0b0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
c0c0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
c0d0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
c0e0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
c0f0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
c100: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
c110: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
c120: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
c130: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
c140: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
c150: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
c160: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
c170: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
c180: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
c190: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
c1a0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
c1b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c1c0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
c1d0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
c1e0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
c1f0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
c200: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
c210: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
c220: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
c230: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c240: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
c250: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
c260: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
c270: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
c280: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
c290: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
c2a0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
c2b0: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
c2c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
c2d0: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
c2e0: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
c2f0: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
c300: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
c310: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
c320: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
c330: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
c340: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
c350: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
c360: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
c370: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
c380: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c390: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
c3a0: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
c3b0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
c3c0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
c3d0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
c3e0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
c3f0: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
c400: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
c410: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
c420: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
c430: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
c440: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
c450: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
c460: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c470: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c480: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
c490: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c4a0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
c4b0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
c4c0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
c4d0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
c4e0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
c4f0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
c500: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
c510: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
c520: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
c530: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
c540: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
c550: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
c560: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
c570: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c580: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
c590: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c5a0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
c5b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c5c0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
c5d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c5e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
c5f0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
c600: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c610: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
c620: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
c630: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
c640: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
c650: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c660: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c670: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c680: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c690: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c6a0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c6b0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c6c0: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c6d0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c6e0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c6f0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c700: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c710: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c720: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c730: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c740: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c750: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c760: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c770: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c780: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c790: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c7a0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c7b0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c7c0: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c7d0: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c7e0: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c7f0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c800: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c810: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c820: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c830: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c840: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c850: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c860: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c870: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c880: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c890: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c8a0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c8b0: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c8c0: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c8d0: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c8e0: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c8f0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c900: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c910: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c920: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c930: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c940: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c950: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c960: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c970: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c980: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c990: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c9a0: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c9b0: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c9c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c9d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c9e0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c9f0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
ca00: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
ca10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
ca20: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
ca30: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
ca40: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
ca50: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
ca60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
ca70: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
ca80: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
ca90: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
caa0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
cab0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
cac0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
cad0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
cae0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
caf0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
cb00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
cb10: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
cb20: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
cb30: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
cb40: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
cb50: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
cb60: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
cb70: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
cb80: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
cb90: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
cba0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
cbb0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
cbc0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
cbd0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
cbe0: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
cbf0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
cc00: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
cc10: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
cc20: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
cc30: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
cc40: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
cc50: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
cc60: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
cc70: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
cc80: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cc90: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cca0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ccb0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
ccc0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ccd0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cce0: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ccf0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cd00: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cd10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cd20: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cd30: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cd40: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cd50: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cd60: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cd70: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cd80: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cd90: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cda0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cdb0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cdc0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cdd0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cde0: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cdf0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ce00: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ce10: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ce20: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
ce30: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
ce40: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
ce50: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
ce60: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
ce70: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
ce80: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
ce90: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
cea0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
ceb0: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
cec0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
ced0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
cee0: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
cef0: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
cf00: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
cf10: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
cf20: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
cf30: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
cf40: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
cf50: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
cf60: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
cf70: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
cf80: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cf90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
cfa0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
cfb0: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
cfc0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
cfd0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
cfe0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
cff0: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
d000: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
d010: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
d020: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
d030: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
d040: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
d050: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
d060: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
d070: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
d080: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
d090: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
d0a0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
d0b0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
d0c0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
d0d0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
d0e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
d0f0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
d100: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
d110: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
d120: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d130: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
d140: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
d150: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
d160: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
d170: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
d180: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
d190: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
d1a0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
d1b0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
d1c0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d1d0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
d1e0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
d1f0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
d200: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d210: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
d220: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
d230: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
d240: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
d250: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
d260: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d270: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
d280: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
d290: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
d2a0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
d2b0: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
d2c0: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
d2d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
d2e0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d2f0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
d300: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
d310: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
d320: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
d330: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
d340: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
d350: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
d360: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
d370: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
d380: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
d390: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
d3a0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
d3b0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
d3c0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
d3d0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
d3e0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
d3f0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
d400: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
d410: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
d420: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
d430: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
d440: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
d450: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
d460: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
d470: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
d480: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
d490: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
d4a0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
d4b0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
d4c0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
d4d0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
d4e0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
d4f0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
d500: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
d510: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
d520: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
d530: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
d540: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
d550: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
d560: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
d570: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
d580: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
d590: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d5a0: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
d5b0: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
d5c0: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
d5d0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
d5e0: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
d5f0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
d600: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
d610: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
d620: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
d630: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d640: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
d650: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d660: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d670: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d680: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d690: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d6a0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d6b0: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d6c0: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d6d0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d6e0: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d6f0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d700: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d710: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d720: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d730: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d740: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d750: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d760: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d770: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d780: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d790: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d7a0: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d7b0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d7c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d7d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d7e0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d7f0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d800: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d810: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d820: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d830: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d840: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d850: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d860: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d870: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d880: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d890: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d8a0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d8b0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d8c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d8d0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d8e0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d8f0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d900: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d910: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d920: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d930: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d940: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d950: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d960: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d970: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d980: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d990: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d9a0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d9b0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d9c0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d9d0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d9e0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d9f0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
da00: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
da10: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
da20: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
da30: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
da40: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
da50: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
da60: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
da70: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
da80: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
da90: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
daa0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
dab0: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
dac0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
dad0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
dae0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
daf0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
db00: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
db10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
db20: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
db30: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
db40: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
db50: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
db60: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
db70: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
db80: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
db90: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
dba0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
dbb0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
dbc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
dbd0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
dbe0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
dbf0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
dc00: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
dc10: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
dc20: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
dc30: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
dc40: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
dc50: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
dc60: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dc70: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
dc80: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
dc90: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
dca0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
dcb0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
dcc0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
dcd0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
dce0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
dcf0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
dd00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
dd10: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
dd20: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
dd30: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
dd40: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
dd50: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
dd60: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
dd70: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
dd80: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
dd90: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
dda0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ddb0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ddc0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ddd0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dde0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ddf0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
de00: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
de10: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
de20: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
de30: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
de40: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
de50: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
de60: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
de70: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
de80: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
de90: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
dea0: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
deb0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
dec0: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
ded0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
dee0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
def0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
df00: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
df10: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
df20: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
df30: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
df40: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
df50: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
df60: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
df70: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
df80: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
df90: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
dfa0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
dfb0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
dfc0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
dfd0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
dfe0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
dff0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
e000: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
e010: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
e020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
e030: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
e040: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
e050: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
e060: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
e070: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
e080: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
e090: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
e0a0: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
e0b0: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
e0c0: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
e0d0: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
e0e0: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
e0f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e100: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
e110: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
e120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e130: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e140: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e150: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e160: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e170: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e180: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e190: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
e1a0: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
e1b0: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
e1c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e1d0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
e1e0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
e1f0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
e200: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
e210: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
e220: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e230: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
e240: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e250: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
e260: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
e270: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
e280: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
e290: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
e2a0: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
e2b0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
e2c0: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
e2d0: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
e2e0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
e2f0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
e300: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
e310: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
e320: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e330: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
e340: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
e350: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
e360: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
e370: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
e380: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
e390: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
e3a0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e3b0: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
e3c0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
e3d0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
e3e0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
e3f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e400: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e410: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
e420: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
e430: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
e440: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
e450: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e460: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
e470: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
e480: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
e490: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
e4a0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
e4b0: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
e4c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e4d0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e4e0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e4f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e500: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e510: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e520: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e530: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
e540: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
e550: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
e560: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e570: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
e580: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e590: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
e5a0: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
e5b0: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
e5c0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e5d0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e5e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e5f0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
e600: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e610: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e620: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e640: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
e650: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e660: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e670: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e680: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e690: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e6a0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e6b0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e6c0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e6d0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e6e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e6f0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e700: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e710: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e720: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e730: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e740: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e750: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e760: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e770: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e780: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e790: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e7a0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e7b0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e7c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e7d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e7e0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e7f0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e800: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e810: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e820: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e830: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e840: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e850: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e860: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e870: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e880: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e890: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e8a0: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e8b0: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e8c0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e8d0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e8e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e8f0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e900: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e910: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e920: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e930: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e940: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e950: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e960: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e970: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e980: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e990: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e9a0: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e9b0: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e9c0: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e9d0: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e9e0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e9f0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
ea00: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
ea10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ea20: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
ea30: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
ea40: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
ea50: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
ea60: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
ea70: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
ea80: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
ea90: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
eaa0: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
eab0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
eac0: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
ead0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
eae0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
eaf0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
eb00: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
eb10: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
eb20: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
eb30: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
eb40: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
eb50: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
eb60: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
eb70: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
eb80: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
eb90: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
eba0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
ebb0: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
ebc0: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
ebd0: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
ebe0: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
ebf0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
ec00: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
ec10: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ec20: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
ec30: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
ec40: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
ec50: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
ec60: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
ec70: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
ec80: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
ec90: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
eca0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
ecb0: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
ecc0: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
ecd0: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
ece0: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
ecf0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
ed00: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
ed10: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
ed20: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
ed30: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
ed40: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
ed50: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
ed60: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
ed70: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
ed80: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
ed90: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
eda0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
edb0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
edc0: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
edd0: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
ede0: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
edf0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
ee00: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
ee10: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
ee20: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
ee30: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
ee40: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
ee50: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
ee60: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
ee70: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ee80: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
ee90: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
eea0: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
eeb0: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
eec0: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
eed0: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
eee0: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
eef0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
ef00: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
ef10: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
ef20: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
ef30: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
ef40: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
ef50: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
ef60: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ef70: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
ef80: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
ef90: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
efa0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
efb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
efc0: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
efd0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
efe0: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
eff0: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
f000: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
f010: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
f020: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
f030: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
f040: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
f050: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
f060: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
f070: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
f080: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
f090: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
f0a0: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
f0b0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
f0c0: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
f0d0: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
f0e0: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
f0f0: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
f100: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
f110: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
f120: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
f130: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
f140: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
f150: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
f160: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
f170: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
f180: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
f190: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
f1a0: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
f1b0: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
f1c0: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
f1d0: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
f1e0: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
f1f0: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
f200: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
f210: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
f220: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
f230: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
f240: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
f250: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
f260: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
f270: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
f280: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
f290: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
f2a0: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
f2b0: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
f2c0: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
f2d0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
f2e0: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
f2f0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
f300: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
f310: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
f320: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
f330: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
f340: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
f350: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
f360: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
f370: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
f380: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
f390: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
f3a0: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
f3b0: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
f3c0: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
f3d0: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
f3e0: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
f3f0: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
f400: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
f410: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
f420: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
f430: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
f440: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
f450: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
f460: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f470: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
f480: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
f490: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
f4a0: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
f4b0: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
f4c0: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
f4d0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f4e0: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
f4f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
f500: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
f510: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
f520: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
f530: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
f540: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
f550: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
f560: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f570: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
f580: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
f590: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f5a0: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
f5b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f5c0: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
f5d0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f5e0: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
f5f0: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
f600: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
f610: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
f620: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
f630: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
f640: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
f650: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
f660: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
f670: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f680: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
f690: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
f6a0: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
f6b0: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
f6c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f6d0: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
f6e0: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
f6f0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
f700: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
f710: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
f720: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f730: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
f740: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
f750: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
f760: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
f770: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
f780: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
f790: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
f7a0: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
f7b0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
f7c0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
f7d0: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
f7e0: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
f7f0: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
f800: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
f810: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
f820: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
f830: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
f840: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f850: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
f860: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f870: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
f880: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f890: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f8a0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f8b0: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
f8c0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f8d0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f8e0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f8f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f900: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f910: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f920: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f930: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
f940: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
f950: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
f960: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
f970: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
f980: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
f990: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
f9a0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f9b0: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
f9c0: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
f9d0: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
f9e0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f9f0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
fa00: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
fa10: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
fa20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fa30: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
fa40: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fa50: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
fa60: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
fa70: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
fa80: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
fa90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
faa0: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
fab0: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
fac0: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
fad0: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
fae0: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
faf0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fb00: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
fb10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
fb20: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
fb30: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
fb40: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
fb50: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
fb60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fb70: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
fb80: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fb90: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
fba0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fbb0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fbc0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fbd0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fbe0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
fbf0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
fc00: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
fc10: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
fc20: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
fc30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
fc40: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
fc50: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
fc60: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
fc70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
fc80: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
fc90: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
fca0: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
fcb0: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
fcc0: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
fcd0: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
fce0: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
fcf0: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
fd00: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
fd10: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
fd20: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
fd30: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
fd40: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
fd50: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
fd60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fd70: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
fd80: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
fd90: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
fda0: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
fdb0: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
fdc0: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
fdd0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
fde0: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
fdf0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
fe00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fe10: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
fe20: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
fe30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fe40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fe50: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
fe60: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fe70: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
fe80: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
fe90: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
fea0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
feb0: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
fec0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
fed0: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
fee0: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
fef0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
ff00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ff10: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
ff20: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
ff30: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
ff40: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
ff50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ff60: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
ff70: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
ff80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
ff90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
ffa0: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
ffb0: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
ffc0: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
ffd0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
ffe0: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
fff0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
10000 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
10010 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
10020 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
10030 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10040 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
10050 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
10060 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
10070 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
10080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10090 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
100a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
100b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
100c0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
100d0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
100e0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
100f0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
10100 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
10110 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
10120 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
10130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
10140 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
10150 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
10160 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
10170 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
10180 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
10190 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
101a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
101b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
101c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
101d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
101e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
101f0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10200 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
10210 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10220 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
10230 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
10240 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
10250 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
10260 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
10270 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
10280 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
102a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
102b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
102c0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
102d0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
102e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
102f0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
10300 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
10310 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
10320 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
10330 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
10340 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
10350 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
10360 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10370 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
10380 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
10390 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
103a0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
103b0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
103c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
103d0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
103e0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
103f0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
10400 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
10410 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
10420 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
10430 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10450 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
10460 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
10470 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
10480 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
10490 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
104a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
104b0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
104c0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
104d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
104e0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
104f0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
10500 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10510 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10520 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
10530 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
10540 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
10550 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
10560 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
10570 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
10580 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10590 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
105a0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
105b0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
105c0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
105d0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
105e0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
105f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
10600 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
10610 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
10620 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
10630 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10640 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
10650 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
10660 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
10670 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
10680 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
10690 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
106a0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
106b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
106c0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
106d0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
106e0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
106f0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
10700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10710 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10720 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
10730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10740 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
10750 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
10760 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10770 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10780 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
10790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
107a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
107b0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
107c0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
107d0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
107e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
107f0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
10800 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10810 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
10820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10830 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
10840 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10850 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10870 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
10880 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
10890 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
108a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
108b0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
108c0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
108d0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
108e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
108f0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10900 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
10910 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
10920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10930 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
10940 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
10950 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10960 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10970 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
10980 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
10990 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
109a0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
109b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
109c0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
109d0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
109e0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
109f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10a00 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
10a10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
10a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
10a30 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
10a40 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
10a50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10a70 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
10a80 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
10a90 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
10aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10ab0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
10ac0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
10ad0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
10ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
10af0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
10b00 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10b10 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
10b20 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
10b30 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
10b40 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
10b50 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
10b60 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
10b70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
10b80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10b90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10ba0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10bb0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10bc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10bd0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10be0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10bf0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10c00 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10c10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10c20 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10c30 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10c40 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10c50 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10c60 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10c70 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
10c80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10c90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10ca0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
10cb0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10cc0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10cd0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10ce0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10cf0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10d00 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10d10 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10d20 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10d30 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10d40 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
10d50 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10d60 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10d70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
10d80 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
10d90 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
10da0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10db0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
10dc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10dd0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10de0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
10df0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
10e00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
10e10 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
10e20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
10e30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10e40 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
10e50 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
10e60 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
10e70 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
10e80 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
10e90 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
10ea0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
10eb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10ec0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
10ed0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
10ee0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
10ef0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
10f00 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
10f10 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
10f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
10f30 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
10f40 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10f50 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10f60 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10f70 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
10f80 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
10f90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
10fa0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
10fb0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
10fc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10fd0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
10fe0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
10ff0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
11000 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
11010 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
11020 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
11030 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
11040 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
11050 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
11060 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11070 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
11080 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11090 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
110a0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
110b0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
110c0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
110d0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
110e0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
110f0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
11100 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
11110 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
11120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11130 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
11140 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
11150 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
11160 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
11170 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
11180 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
11190 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
111a0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
111b0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
111c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
111d0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
111e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
111f0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
11200 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
11210 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
11220 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
11240 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
11250 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
11260 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
11270 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
11280 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
11290 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
112a0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
112b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
112c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
112d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
112e0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
112f0 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
11300 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
11310 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
11320 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
11330 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
11340 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
11350 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
11360 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
11370 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
11380 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11390 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
113a0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
113b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
113c0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
113d0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
113e0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
113f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
11400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
11410 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11420 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
11430 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
11440 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
11450 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
11460 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
11470 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
11480 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
11490 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
114a0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
114b0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
114c0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
114d0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
114e0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
114f0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
11500 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
11510 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
11520 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
11530 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
11540 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
11550 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
11560 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
11570 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
11580 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
11590 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
115a0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
115b0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
115c0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
115d0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
115e0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
115f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
11600 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
11610 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
11620 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
11630 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
11640 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
11650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
11660 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
11670 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
11680 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
11690 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
116a0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
116b0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
116c0 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
116d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
116e0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
116f0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
11700 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
11710 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
11720 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
11730 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
11740 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
11750 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
11760 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
11770 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
11780 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
11790 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
117a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
117b0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
117c0 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
117d0 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
117e0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
117f0 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
11800 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
11810 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
11820 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
11830 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
11840 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
11850 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
11860 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
11870 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11880 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11890 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
118a0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
118b0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
118c0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
118d0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
118e0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
118f0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
11900 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
11910 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
11920 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
11930 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
11940 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
11950 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
11960 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
11970 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
11980 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11990 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
119a0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
119b0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
119c0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
119d0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
119e0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
119f0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
11a00 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
11a10 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
11a20 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
11a30 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
11a40 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
11a50 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
11a60 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
11a70 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
11a80 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11a90 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
11aa0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
11ab0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
11ac0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
11ad0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
11ae0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
11af0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
11b00 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11b10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11b20 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
11b30 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
11b40 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
11b50 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
11b60 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
11b70 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
11b80 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11b90 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
11ba0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
11bb0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
11bc0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
11bd0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
11be0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
11bf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
11c00 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
11c10 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
11c20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11c30 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11c40 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11c50 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11c60 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11c70 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11c80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11c90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11ca0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11cb0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
11cc0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
11cd0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11ce0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11cf0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11d00 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
11d10 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
11d20 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
11d30 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11d40 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11d50 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11d60 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11d70 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11d90 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11da0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11db0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11dc0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11dd0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
11de0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
11df0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
11e00 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
11e10 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
11e20 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
11e30 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11e40 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11e50 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11e60 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11e70 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11e80 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11e90 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11ea0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11eb0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11ec0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11ed0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
11ee0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
11ef0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
11f00 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
11f10 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
11f20 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
11f30 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11f40 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11f50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11f60 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11f70 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11f80 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11f90 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11fa0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11fb0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11fc0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11fd0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11fe0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11ff0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
12000 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
12010 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
12020 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
12030 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
12040 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
12050 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
12060 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12070 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
12080 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
12090 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
120a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
120b0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
120c0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
120d0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
120e0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
120f0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
12100 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
12110 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
12120 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
12130 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
12140 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
12150 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
12160 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
12170 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
12180 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
12190 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
121a0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
121b0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
121c0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
121d0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
121e0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
121f0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
12200 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
12210 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
12220 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
12230 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
12240 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
12250 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
12260 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
12270 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
12280 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
12290 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
122a0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
122b0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
122c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
122d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
122e0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
122f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
12300 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
12310 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
12320 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
12330 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
12340 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
12350 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
12360 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
12370 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
12380 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
12390 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
123a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
123b0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
123c0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
123d0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
123e0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
123f0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
12400 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
12410 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
12420 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
12430 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
12440 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
12450 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
12460 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
12470 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
12480 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
12490 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
124a0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
124b0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
124c0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
124d0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
124e0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
124f0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
12500 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
12510 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
12520 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
12530 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
12540 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
12550 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
12560 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
12570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
12580 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
12590 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
125a0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
125b0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
125c0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
125d0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
125e0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
125f0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
12600 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
12610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12620 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
12630 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
12640 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12650 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12660 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
12670 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
12680 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
12690 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
126a0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
126b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
126c0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
126d0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
126e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
126f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12700 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
12710 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
12720 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
12730 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
12740 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
12750 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
12770 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
12780 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
12790 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
127a0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
127b0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
127c0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
127d0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
127e0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
127f0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
12800 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
12810 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
12820 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
12830 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
12840 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
12850 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
12860 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
12870 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
12880 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12890 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
128a0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
128b0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
128c0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
128d0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
128e0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
128f0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
12900 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
12910 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
12920 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
12930 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
12940 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
12950 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
12960 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
12970 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12980 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12990 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
129a0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
129b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
129c0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
129d0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
129e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
129f0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
12a00 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
12a10 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
12a20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
12a30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
12a40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
12a50 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
12a60 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
12a70 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
12a80 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12a90 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
12aa0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12ab0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12ac0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12ad0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
12ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12af0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
12b00 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12b10 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
12b20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
12b30 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
12b40 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12b50 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12b60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12b70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
12b80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12b90 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
12ba0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
12bb0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
12bc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
12bd0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
12be0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
12bf0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
12c00 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
12c10 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
12c20 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
12c30 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12c40 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12c50 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12c60 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12c70 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12c80 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12c90 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
12ca0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
12cb0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
12cc0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
12cd0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
12ce0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12cf0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
12d00 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
12d10 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
12d20 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
12d30 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12d40 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12d50 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12d60 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12d70 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12d80 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12da0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12db0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12dc0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12dd0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
12de0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
12df0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
12e00 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
12e10 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
12e20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
12e30 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12e40 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12e50 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12e60 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12e70 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12e80 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12e90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12ea0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12eb0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12ec0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12ed0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
12ee0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12ef0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
12f00 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
12f10 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
12f20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
12f30 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12f40 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12f50 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12f60 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12f70 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12f80 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12f90 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12fa0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12fb0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12fc0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12fd0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12fe0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12ff0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
13000 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
13010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13020 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
13030 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
13040 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
13050 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
13060 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13070 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
13080 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
13090 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
130a0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
130b0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
130c0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
130d0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
130e0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
130f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
13100 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
13110 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
13120 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
13130 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
13140 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
13150 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
13160 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
13170 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
13180 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
13190 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
131a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
131b0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
131c0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
131d0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
131e0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
131f0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
13200 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
13210 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
13220 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
13230 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
13240 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
13250 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
13260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13270 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
13280 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
13290 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
132a0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
132b0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
132c0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
132d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
132e0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
132f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13300 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13310 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13320 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
13330 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13340 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
13350 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
13360 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
13370 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
13380 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13390 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
133a0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
133b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
133c0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
133d0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
133e0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
133f0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
13400 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
13410 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
13420 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
13430 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
13440 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
13450 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
13460 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
13470 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
13480 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
13490 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
134a0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
134b0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
134c0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
134d0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
134e0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
134f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
13500 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
13510 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
13520 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
13530 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
13540 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
13550 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
13560 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
13570 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
13580 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13590 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
135a0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
135b0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
135c0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
135d0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
135e0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
135f0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
13600 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
13610 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
13620 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
13630 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
13640 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
13650 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
13660 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
13670 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
13680 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13690 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
136a0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
136b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
136c0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
136d0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
136e0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
136f0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
13700 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
13710 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
13720 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
13730 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
13740 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
13750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13760 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
13770 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
13780 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13790 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
137a0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
137b0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
137c0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
137d0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
137e0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
137f0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13800 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13810 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13820 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
13830 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
13840 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
13850 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13860 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
13870 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
13880 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13890 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
138a0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
138b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
138c0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
138d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
138e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
138f0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13900 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13910 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13920 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
13930 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
13940 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
13950 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
13960 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
13970 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
13980 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
139a0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
139b0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
139c0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
139d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
139e0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
139f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13a00 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
13a10 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
13a20 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
13a30 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
13a40 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
13a50 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
13a60 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
13a70 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
13a80 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13a90 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
13aa0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
13ab0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13ac0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
13ad0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
13ae0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
13af0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
13b00 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
13b10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
13b20 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
13b30 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
13b40 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
13b50 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
13b60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
13b70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13b80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13b90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
13ba0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
13bb0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
13bc0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
13bd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13be0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
13bf0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13c00 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
13c10 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
13c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
13c30 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13c40 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13c50 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13c60 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13c70 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13c80 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13c90 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
13ca0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
13cb0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
13cc0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
13cd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
13ce0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
13cf0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13d00 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
13d10 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
13d20 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
13d30 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13d40 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13d50 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13d60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13d70 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13d80 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13d90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13da0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13db0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13dc0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13dd0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
13de0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
13df0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
13e00 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
13e10 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13e20 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13e30 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13e40 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13e50 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13e60 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13e70 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13e80 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13e90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13ea0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13eb0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13ec0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13ed0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
13ee0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
13ef0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13f00 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13f10 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13f20 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13f30 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13f40 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13f50 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13f60 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13f70 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13f80 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13f90 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13fa0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13fb0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13fc0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13fd0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13fe0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13ff0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
14000 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
14010 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
14020 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
14030 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
14040 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
14050 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
14060 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
14070 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
14080 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
14090 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
140a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
140b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
140c0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
140d0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
140e0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
140f0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
14100 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
14110 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
14120 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
14130 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
14140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
14150 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
14160 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
14170 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
14180 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
14190 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
141a0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
141b0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
141c0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
141d0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
141e0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
141f0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
14200 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
14210 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
14220 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
14230 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
14240 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
14250 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
14260 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
14270 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
14280 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
14290 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
142a0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
142b0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
142c0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
142d0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
142e0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
142f0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
14300 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
14310 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
14320 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
14330 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
14340 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
14350 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
14360 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
14370 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
14380 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
14390 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
143a0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
143b0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
143c0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
143d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
143e0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
143f0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
14400 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
14410 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
14420 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
14430 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
14440 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
14450 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
14460 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
14470 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
14480 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
14490 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
144a0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
144b0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
144c0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
144d0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
144e0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
144f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
14500 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
14510 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14520 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
14530 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
14540 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
14550 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
14560 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
14570 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
14580 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14590 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
145a0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
145b0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
145c0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
145d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
145e0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
145f0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
14600 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
14610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14620 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
14630 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14640 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
14650 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
14660 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
14670 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
14680 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
14690 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
146a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
146b0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
146c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
146d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
146e0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
146f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14700 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14710 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
14720 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
14730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
14740 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
14750 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
14760 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
14770 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14780 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
14790 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
147a0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
147b0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
147c0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
147d0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
147e0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
147f0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
14800 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
14810 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
14820 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
14830 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
14840 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
14850 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
14860 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14870 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
14880 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14890 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
148a0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
148b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
148c0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
148d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
148e0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
148f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14900 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
14910 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14920 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
14930 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
14940 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
14950 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
14960 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
14970 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
14980 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
149a0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
149b0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
149c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
149d0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
149e0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
149f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14a00 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
14a10 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
14a20 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
14a30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
14a40 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
14a50 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14a60 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14a70 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14a80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14a90 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14aa0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14ab0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
14ac0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
14ad0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
14ae0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
14af0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14b00 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
14b10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
14b20 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
14b30 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
14b40 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
14b50 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
14b60 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
14b70 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
14b80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
14b90 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
14ba0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
14bb0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
14bc0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
14bd0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
14be0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
14bf0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
14c00 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
14c10 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
14c20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
14c30 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
14c40 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
14c50 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
14c60 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
14c70 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
14c80 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
14c90 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
14ca0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
14cb0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
14cc0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
14cd0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
14ce0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
14cf0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
14d00 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
14d10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14d20 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
14d30 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
14d40 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
14d50 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
14d60 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
14d70 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
14d80 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
14d90 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
14da0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
14db0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
14dc0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
14dd0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
14de0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
14df0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
14e00 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
14e10 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
14e20 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
14e30 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
14e40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14e50 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
14e60 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
14e70 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14e80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
14e90 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14ea0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
14eb0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
14ec0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14ed0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
14ee0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
14ef0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
14f00 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
14f10 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
14f20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
14f30 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
14f40 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
14f50 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14f60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
14f70 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14f80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
14f90 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14fa0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14fb0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14fc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14fd0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14fe0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14ff0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
15000 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15010 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
15020 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
15030 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
15040 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
15050 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
15060 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
15070 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15080 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
15090 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
150a0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
150b0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
150c0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
150d0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
150e0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
150f0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
15100 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
15110 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
15120 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
15130 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
15140 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
15150 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15160 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15170 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
15180 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15190 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
151a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
151b0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
151c0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
151d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
151e0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
151f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15200 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
15210 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15220 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
15230 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15240 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
15250 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
15260 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
15270 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
15280 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
15290 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
152a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
152b0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
152c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
152d0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
152e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
152f0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
15300 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
15310 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
15320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
15330 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
15340 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
15350 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
15360 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
15370 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
15380 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
15390 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
153a0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
153b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
153c0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
153d0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
153e0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
153f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
15400 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
15410 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
15420 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
15430 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
15440 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
15450 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
15460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
15470 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
15480 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15490 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
154a0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
154b0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
154c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
154d0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
154e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
154f0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
15500 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
15510 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
15520 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
15530 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15540 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
15550 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
15560 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
15570 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
15580 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
15590 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
155a0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
155b0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
155c0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
155d0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
155e0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
155f0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
15600 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
15610 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
15620 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
15630 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
15640 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
15650 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
15660 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
15670 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
15680 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
15690 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
156a0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
156b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
156c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
156d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
156e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
156f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15700 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15710 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15720 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
15730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
15740 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
15750 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
15760 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
15770 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
15780 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15790 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
157a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
157b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
157c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
157d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
157e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
157f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15800 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15810 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15820 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
15830 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
15840 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
15850 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
15860 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
15870 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
15880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15890 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
158a0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
158b0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
158c0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
158d0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
158e0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
158f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15900 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15910 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15920 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15930 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
15940 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
15950 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
15960 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
15970 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
15980 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
15990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
159a0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
159b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
159c0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
159d0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
159e0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
159f0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
15a00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15a10 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
15a20 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
15a30 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
15a40 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
15a50 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
15a60 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
15a70 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
15a80 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
15a90 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
15aa0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
15ab0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
15ac0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
15ad0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
15ae0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
15af0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
15b00 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
15b10 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15b20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
15b30 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
15b40 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
15b50 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
15b60 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
15b70 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
15b80 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
15b90 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
15ba0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
15bb0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
15bc0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
15bd0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
15be0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
15bf0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
15c00 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
15c10 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
15c20 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
15c30 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
15c40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
15c50 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
15c60 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
15c70 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
15c80 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
15c90 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
15ca0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
15cb0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
15cc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
15cd0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
15ce0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
15cf0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
15d00 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
15d10 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
15d20 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
15d30 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
15d40 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
15d50 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
15d60 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
15d70 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
15d80 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
15d90 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
15da0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
15db0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
15dc0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
15dd0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
15de0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
15df0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
15e00 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
15e10 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
15e20 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
15e30 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
15e40 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
15e50 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
15e60 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
15e70 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
15e80 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
15e90 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
15ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
15eb0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
15ec0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
15ed0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
15ee0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15ef0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
15f00 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15f10 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15f20 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15f30 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15f40 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15f50 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15f60 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15f70 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15f80 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
15f90 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
15fa0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
15fb0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
15fc0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
15fd0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
15fe0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
15ff0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
16000 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
16010 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
16020 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
16030 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
16040 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
16050 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
16060 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
16070 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
16080 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
16090 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
160a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
160b0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
160c0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
160d0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
160e0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
160f0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
16100 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
16110 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
16120 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
16130 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
16140 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
16150 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
16160 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
16170 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16180 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
16190 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
161a0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
161b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
161c0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
161d0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
161e0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
161f0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
16200 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16210 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
16220 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
16230 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
16240 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
16250 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
16260 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
16270 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
16280 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
16290 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
162a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
162b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
162c0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
162d0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
162e0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
162f0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
16300 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
16310 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
16320 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
16330 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16340 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
16350 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
16360 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
16370 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
16380 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16390 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
163a0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
163b0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
163c0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
163d0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
163e0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
163f0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
16400 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
16410 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
16420 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
16430 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
16440 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
16450 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16460 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
16470 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
16480 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
16490 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
164a0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
164b0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
164c0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
164d0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
164e0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
164f0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
16500 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
16510 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
16520 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
16530 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
16540 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
16550 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
16560 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
16570 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
16580 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
16590 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
165a0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
165b0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
165c0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
165d0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
165e0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
165f0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
16600 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
16610 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
16620 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
16630 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
16640 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16650 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
16660 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
16670 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
16680 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
16690 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
166a0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
166b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
166c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
166d0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
166e0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
166f0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
16700 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
16710 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
16720 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
16730 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
16740 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
16750 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
16760 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
16770 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
16780 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
16790 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
167a0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
167b0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
167c0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
167d0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
167e0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
167f0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
16800 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
16810 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
16820 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
16830 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
16840 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
16850 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
16860 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
16870 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
16880 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
16890 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
168a0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
168b0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
168c0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
168d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
168e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
168f0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
16900 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
16910 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
16920 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
16930 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
16940 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
16950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
16960 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
16970 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
16980 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
16990 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
169a0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
169b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
169c0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
169d0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
169e0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
169f0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
16a00 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
16a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16a20 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
16a30 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
16a40 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
16a50 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
16a60 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
16a70 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
16a80 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
16a90 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
16aa0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
16ab0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
16ac0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
16ad0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
16ae0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
16af0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
16b00 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
16b10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16b20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
16b30 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
16b40 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
16b50 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
16b60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
16b70 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
16b80 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
16b90 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
16ba0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
16bb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
16bc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16bd0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
16be0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
16bf0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
16c00 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
16c10 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
16c20 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
16c30 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
16c40 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
16c50 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
16c60 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
16c70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16c80 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
16c90 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
16ca0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
16cb0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
16cc0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
16cd0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
16ce0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
16cf0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
16d00 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
16d10 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
16d20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
16d30 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
16d40 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
16d50 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
16d60 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
16d70 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
16d80 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
16d90 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
16da0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
16db0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
16dc0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
16dd0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
16de0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
16df0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
16e00 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
16e10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
16e20 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
16e30 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
16e40 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
16e50 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
16e60 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
16e70 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
16e80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16e90 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
16ea0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
16eb0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
16ec0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
16ed0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
16ee0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
16ef0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16f00 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
16f10 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
16f20 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
16f30 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
16f40 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
16f50 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
16f60 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16f70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
16f80 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
16f90 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
16fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
16fb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
16fc0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
16fd0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
16fe0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
16ff0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
17000 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
17010 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
17020 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
17030 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
17040 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
17050 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
17060 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
17070 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
17090 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
170a0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
170b0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
170c0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
170d0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
170e0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
170f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17100 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
17110 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
17120 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17130 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
17140 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
17150 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
17160 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
17170 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
17180 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
17190 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
171a0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
171b0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
171c0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
171d0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
171e0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
171f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
17200 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
17210 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
17220 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
17230 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
17240 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
17250 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
17260 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
17270 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
17280 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
17290 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
172a0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
172b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
172c0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
172d0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
172e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
172f0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
17300 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
17310 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
17320 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
17330 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
17340 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
17350 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
17360 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
17370 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
17380 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
17390 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
173a0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
173b0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
173c0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
173d0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
173e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
173f0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
17400 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
17410 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
17420 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
17430 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
17440 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
17450 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
17460 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
17470 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
17480 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
17490 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
174a0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
174b0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
174c0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
174d0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
174e0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
174f0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
17500 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
17510 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
17520 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
17530 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
17540 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
17550 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
17560 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
17570 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
17580 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
17590 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
175a0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
175b0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
175c0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
175d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
175e0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
175f0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
17600 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
17610 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17620 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
17630 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
17640 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
17650 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
17660 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
17670 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
17680 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
17690 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
176a0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
176b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
176c0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
176d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
176e0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
176f0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
17700 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
17710 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
17720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
17730 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
17740 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
17750 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
17760 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
17770 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
17780 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
17790 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
177a0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
177b0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
177c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
177d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
177e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
177f0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
17800 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
17810 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
17820 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
17830 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
17840 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
17850 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
17860 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
17870 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
17880 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
17890 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
178a0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
178b0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
178c0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
178d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
178e0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
178f0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
17900 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
17910 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
17920 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
17930 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
17940 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
17950 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
17960 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17970 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
17980 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
17990 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
179a0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
179b0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
179c0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
179d0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
179e0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
179f0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
17a00 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
17a10 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
17a20 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
17a30 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
17a40 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
17a50 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
17a60 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
17a70 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
17a80 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
17a90 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
17aa0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
17ab0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
17ac0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
17ad0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
17ae0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
17af0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
17b00 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
17b10 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17b20 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
17b30 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
17b40 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
17b50 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
17b60 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
17b70 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
17b80 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
17b90 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
17ba0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
17bb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
17bc0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
17bd0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
17be0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
17bf0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
17c00 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
17c10 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
17c20 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
17c30 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
17c40 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
17c50 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
17c60 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
17c70 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
17c80 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
17c90 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
17ca0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
17cb0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
17cc0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
17cd0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
17ce0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
17cf0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
17d00 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
17d10 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
17d20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
17d30 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
17d40 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
17d50 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
17d60 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
17d70 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
17d80 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
17d90 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
17da0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
17db0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
17dc0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
17dd0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
17de0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
17df0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
17e00 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
17e10 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
17e20 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
17e30 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
17e40 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
17e50 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
17e60 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
17e70 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
17e80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
17e90 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
17ea0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
17eb0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
17ec0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
17ed0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
17ee0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
17ef0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
17f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
17f10 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
17f20 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
17f30 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
17f40 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
17f50 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
17f60 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
17f70 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
17f80 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
17f90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
17fa0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
17fb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
17fc0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
17fd0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
17fe0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
17ff0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
18000 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
18010 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18020 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18030 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
18040 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
18050 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
18060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
18070 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
18080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18090 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
180a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
180b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
180c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
180d0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
180e0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
180f0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
18100 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
18110 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
18120 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
18130 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
18140 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18150 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18160 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
18170 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
18180 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
18190 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
181a0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
181b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
181c0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
181d0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
181e0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
181f0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
18200 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
18210 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
18220 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
18230 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
18240 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
18250 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
18260 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
18270 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
18280 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
18290 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
182a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
182b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
182c0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
182d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
182e0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
182f0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
18300 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
18310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18320 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
18330 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
18340 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
18350 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
18360 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
18370 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
18380 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
18390 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
183a0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
183b0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
183c0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
183d0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
183e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
183f0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
18400 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
18410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18420 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
18430 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
18440 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
18450 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
18460 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
18470 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
18480 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
18490 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
184a0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
184b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
184c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
184d0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
184e0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
184f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
18500 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18510 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
18520 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18530 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
18540 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18550 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
18560 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
18570 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
18580 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
18590 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
185a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
185b0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
185c0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
185d0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
185e0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
185f0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
18600 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
18610 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
18620 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
18630 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
18640 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
18650 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
18660 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
18670 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
18680 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
18690 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
186a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
186b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
186c0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
186d0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
186e0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
186f0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
18700 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
18710 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
18720 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
18730 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
18740 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
18750 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
18760 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
18770 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
18780 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
18790 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
187a0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
187b0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
187c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
187d0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
187e0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
187f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
18800 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
18810 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
18820 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
18830 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
18840 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
18850 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
18860 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
18870 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
18880 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
18890 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
188a0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
188b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
188c0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
188d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
188e0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
188f0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
18900 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
18910 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18920 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
18930 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
18940 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
18950 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
18960 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
18970 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
18980 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
18990 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
189a0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
189b0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
189c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
189d0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
189e0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
189f0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
18a00 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
18a10 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
18a20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
18a30 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
18a40 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
18a50 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
18a60 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
18a70 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
18a80 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
18a90 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
18aa0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
18ab0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
18ac0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
18ad0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
18ae0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
18af0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
18b00 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
18b10 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
18b20 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
18b30 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
18b40 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
18b50 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
18b60 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
18b70 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
18b80 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
18b90 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
18ba0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18bb0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
18bc0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
18bd0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
18be0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
18bf0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
18c00 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
18c10 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
18c20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
18c30 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
18c40 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
18c50 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
18c60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
18c70 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
18c80 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
18c90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
18ca0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
18cb0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
18cc0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
18cd0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
18ce0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
18cf0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
18d00 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
18d10 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
18d20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
18d30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18d40 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
18d50 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
18d60 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
18d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18d80 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
18d90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18da0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
18db0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
18dc0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
18dd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18de0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
18df0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
18e00 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
18e10 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
18e20 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
18e30 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
18e40 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
18e50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
18e60 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
18e70 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
18e80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
18e90 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
18ea0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
18eb0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
18ec0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
18ed0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
18ee0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
18ef0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
18f00 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
18f10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18f20 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
18f30 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
18f40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18f50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
18f60 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
18f70 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
18f80 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
18f90 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
18fa0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
18fb0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
18fc0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
18fd0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
18fe0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
18ff0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
19000 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
19010 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
19020 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
19030 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
19040 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
19050 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
19060 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
19070 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
19080 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
19090 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
190a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
190b0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
190c0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
190d0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
190e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
190f0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
19100 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
19110 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
19120 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
19130 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
19140 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
19150 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
19160 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
19170 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
19180 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19190 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
191a0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
191b0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
191c0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
191d0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
191e0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
191f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
19200 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
19210 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
19220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19230 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
19240 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
19250 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
19260 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
19270 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
19280 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
19290 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
192a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
192b0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
192c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
192d0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
192e0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
192f0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
19300 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
19310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19320 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
19330 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
19340 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
19350 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
19360 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
19370 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
19380 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
19390 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
193a0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
193b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
193c0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
193d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
193e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
193f0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
19400 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
19410 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
19420 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
19430 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
19440 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
19450 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
19460 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19470 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
19480 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
19490 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
194a0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
194b0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
194c0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
194d0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
194e0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
194f0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
19500 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
19510 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19520 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
19530 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
19540 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
19550 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
19560 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
19570 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19580 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
19590 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
195a0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
195b0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
195c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
195d0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
195e0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
195f0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
19600 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
19610 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
19620 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
19630 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
19640 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
19650 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
19660 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
19670 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
19680 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
19690 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
196a0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
196b0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
196c0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
196d0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
196e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
196f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19700 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
19710 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
19720 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
19730 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
19740 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
19750 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19760 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19780 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
19790 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
197a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
197b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
197c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
197d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
197e0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
197f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
19800 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19820 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
19830 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
19840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
19850 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19870 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
19880 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
19890 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
198a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
198b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
198c0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
198d0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
198e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
198f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19910 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
19920 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
19930 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
19940 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19960 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
19970 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
19980 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
19990 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
199a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
199b0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
199c0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
199d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
199e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
199f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19a00 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
19a10 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
19a20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
19a30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19a40 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19a50 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
19a60 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
19a70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19a80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19a90 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
19aa0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
19ab0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
19ac0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
19ad0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19ae0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
19af0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
19b00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19b10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19b20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19b30 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
19b40 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
19b50 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
19b60 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
19b70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19b80 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
19b90 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
19ba0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
19bb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19bc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19bd0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
19be0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
19bf0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
19c00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19c20 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
19c30 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
19c40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
19c50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c70 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
19c80 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
19c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19ca0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19cc0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
19cd0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
19ce0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
19cf0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
19d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19d10 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
19d20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
19d30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
19d40 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
19d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19d60 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
19d70 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
19d80 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
19d90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
19db0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
19dc0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
19dd0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
19de0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
19e00 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
19e10 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
19e20 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
19e30 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
19e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
19e50 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
19e60 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
19e70 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
19e80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
19ea0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
19eb0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
19ec0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
19ed0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19ee0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
19ef0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
19f00 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
19f10 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
19f20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19f30 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
19f40 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
19f50 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
19f60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19f70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19f80 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
19f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
19fa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19fb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19fc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19fd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
19fe0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
19ff0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1a000 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1a010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a020 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1a030 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1a040 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1a050 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1a060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a070 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1a080 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1a090 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1a0a0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1a0b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a0c0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1a0d0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1a0e0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1a0f0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1a100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a110 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1a120 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1a130 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1a140 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1a150 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1a160 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1a170 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1a180 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1a190 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1a1a0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1a1b0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1a1c0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1a1d0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1a1e0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1a1f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1a200 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a210 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1a220 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1a230 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1a240 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1a250 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1a260 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1a270 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1a280 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1a290 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1a2a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1a2b0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1a2c0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1a2d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1a2e0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1a2f0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1a300 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1a310 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1a320 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1a330 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1a340 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1a350 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1a360 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1a370 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1a380 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1a390 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1a3a0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1a3b0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1a3c0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1a3d0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1a3e0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1a3f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1a400 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1a410 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1a420 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1a430 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1a440 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1a450 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1a460 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1a470 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1a480 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1a490 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1a4a0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1a4b0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1a4c0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1a4d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1a4e0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1a4f0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1a500 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1a510 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1a520 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1a530 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1a540 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1a550 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1a560 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1a570 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1a580 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1a590 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1a5a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1a5b0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1a5c0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1a5d0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1a5e0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1a5f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1a600 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1a610 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1a620 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1a630 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1a640 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1a650 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1a660 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1a670 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1a680 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1a690 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1a6a0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1a6b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1a6c0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1a6d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1a6e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1a6f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1a700 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1a710 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1a720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a730 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1a740 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1a750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1a760 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1a770 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1a780 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1a790 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1a7a0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1a7b0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1a7c0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1a7d0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1a7e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1a7f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a800 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1a810 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1a820 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a830 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1a840 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1a850 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1a860 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1a870 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1a880 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1a890 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1a8a0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1a8b0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
1a8c0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
1a8d0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
1a8e0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
1a8f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
1a900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1a910 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
1a920 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
1a930 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
1a940 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
1a950 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
1a960 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
1a970 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a  allback X..**.**
1a980 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
1a990 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a9a0 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
1a9b0 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
1a9c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1a9d0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
1a9e0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
1a9f0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
1aa00 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
1aa10 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
1aa20 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
1aa30 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
1aa40 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1aa50 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
1aa60 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
1aa70 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
1aa80 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
1aa90 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
1aaa0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
1aab0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1aac0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1aad0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1aae0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1aaf0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1ab00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1ab10 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1ab20 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1ab30 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1ab40 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1ab50 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1ab60 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1ab70 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ab80 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1ab90 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1aba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1abb0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1abc0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1abd0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1abe0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1abf0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1ac00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1ac10 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1ac20 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ac30 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1ac40 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1ac50 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1ac60 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
1ac70 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1ac80 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1ac90 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1aca0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1acb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1acc0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1acd0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1ace0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1acf0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1ad00 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1ad10 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
1ad20 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
1ad30 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
1ad40 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1ad50 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1ad60 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1ad70 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1ad80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1ad90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ada0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1adb0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1adc0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1add0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1ade0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1adf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1ae00 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1ae10 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1ae20 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1ae30 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1ae40 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1ae50 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1ae60 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1ae70 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1ae80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ae90 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1aea0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1aeb0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1aec0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1aed0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1aee0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1aef0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1af00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1af10 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1af20 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1af30 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1af40 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1af50 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1af60 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1af70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1af80 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1af90 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1afa0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1afb0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1afc0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1afd0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1afe0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1aff0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1b000 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1b010 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1b020 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1b030 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1b040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1b050 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1b060 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1b070 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1b080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1b090 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1b0a0 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1b0b0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1b0c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1b0d0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1b0e0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1b0f0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1b100 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1b110 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1b120 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1b130 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1b140 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1b150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b160 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1b170 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1b180 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1b190 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1b1a0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1b1b0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1b1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b1d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1b1e0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1b1f0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1b200 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1b210 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1b220 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1b230 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1b240 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1b250 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1b260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1b270 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1b280 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1b290 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b2a0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1b2b0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1b2c0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1b2d0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1b2e0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1b2f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1b300 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1b310 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1b320 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1b330 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e  REDCACHE],.** an
1b340 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1b350 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1b360 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1b370 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1b380 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1b390 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1b3a0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1b3b0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1b3c0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1b3d0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1b3e0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1b3f0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1b400 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1b410 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1b420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1b430 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1b440 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1b450 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1b460 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1b470 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1b480 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1b490 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1b4a0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1b4b0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1b4c0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1b4d0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1b4e0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1b4f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1b500 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1b510 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1b520 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1b530 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1b540 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1b550 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1b560 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b570 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b580 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1b590 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1b5a0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
1b5b0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1b5c0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1b5d0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1b5e0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1b5f0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1b600 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b610 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b620 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1b630 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
1b640 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1b650 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b660 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
1b670 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
1b680 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
1b690 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d  r one of the com
1b6a0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1b6b0 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a  above combined.*
1b6c0 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
1b6d0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1b6e0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1b6f0 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53  ULLMUTEX],.** [S
1b700 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1b710 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b  DCACHE] and/or [
1b720 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1b730 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  ATECACHE] flags,
1b740 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1b750 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1b760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1b770 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1b780 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1b790 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1b7a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b7b0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1b7c0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1b7d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1b7e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1b7f0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1b800 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1b810 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1b820 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1b830 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1b840 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1b850 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1b860 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1b870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b880 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1b890 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1b8a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1b8b0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1b8c0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1b8d0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1b8e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1b8f0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1b900 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1b910 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1b920 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1b930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b940 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1b950 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1b960 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1b970 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b980 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1b990 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1b9a0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1b9b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1b9c0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1b9d0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1b9e0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1b9f0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1ba00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ba10 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1ba20 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1ba30 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1ba40 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1ba50 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1ba60 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1ba70 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1ba80 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1ba90 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1baa0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1bab0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1bac0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1bad0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1bae0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1baf0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1bb00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1bb10 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1bb20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1bb30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1bb40 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1bb50 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1bb60 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1bb70 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1bb80 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1bb90 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1bba0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1bbb0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1bbc0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1bbd0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1bbe0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1bbf0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1bc00 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1bc10 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1bc20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1bc30 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1bc40 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1bc50 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1bc60 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1bc70 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1bc80 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1bc90 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1bca0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1bcb0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1bcc0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1bcd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1bce0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1bcf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1bd00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1bd10 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  sed..**.** ^The 
1bd20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1bd30 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1bd40 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1bd50 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1bd60 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1bd70 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1bd80 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1bd90 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1bda0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1bdb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bdc0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1bdd0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1bde0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1bdf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1be00 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1be10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1be20 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1be30 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1be40 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1be50 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1be60 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1be70 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1be80 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1be90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1bea0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1beb0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1bec0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1bed0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1bee0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1bef0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1bf00 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1bf10 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1bf20 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1bf30 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1bf40 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1bf50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1bf60 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1bf70 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  2()..*/.int sqli
1bf80 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1bf90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1bfa0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1bfb0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1bfc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1bfd0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1bfe0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1bff0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1c000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1c010 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1c020 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c030 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c040 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1c050 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1c060 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1c070 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1c080 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1c090 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1c0a0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1c0b0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1c0c0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1c0d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1c0e0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1c0f0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1c100 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1c110 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1c120 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1c130 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1c140 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1c150 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1c160 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1c170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1c180 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1c190 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
1c1a0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1c1b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1c1c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1c1d0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1c1e0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1c1f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1c200 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c210 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1c220 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1c230 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1c240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c250 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1c260 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1c270 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1c280 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1c290 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1c2a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1c2b0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1c2c0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1c2d0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
1c2e0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1c2f0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
1c300 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
1c310 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1c320 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
1c330 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
1c340 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
1c350 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
1c360 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
1c370 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
1c380 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c390 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1c3a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1c3b0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1c3c0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1c3d0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1c3e0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1c3f0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1c400 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1c410 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
1c420 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1c430 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1c440 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1c450 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1c460 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1c470 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1c480 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1c490 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1c4a0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1c4b0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1c4c0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1c4d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1c4e0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1c4f0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1c500 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1c510 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
1c520 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1c530 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1c540 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1c550 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1c560 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1c570 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1c580 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1c590 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1c5a0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1c5b0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1c5c0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1c5d0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1c5e0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1c5f0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1c600 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1c610 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1c620 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1c630 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1c640 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1c650 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1c660 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1c670 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1c680 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1c690 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1c6a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c6b0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1c6c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1c6d0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1c6e0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1c6f0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1c700 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1c710 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1c720 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1c730 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1c740 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1c750 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1c760 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1c770 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1c780 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1c790 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1c7a0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1c7b0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1c7c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1c7d0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1c7e0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1c7f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1c800 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1c810 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1c820 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1c830 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1c840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c850 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1c860 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
1c870 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1c880 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1c890 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1c8a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1c8b0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1c8c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1c8d0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1c8e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c8f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1c900 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1c910 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1c920 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1c930 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1c940 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1c950 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1c960 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1c970 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1c980 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1c990 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1c9a0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1c9b0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1c9c0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1c9d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1c9e0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1c9f0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1ca00 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1ca10 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1ca20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1ca30 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1ca40 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1ca50 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1ca60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1ca70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1ca80 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1ca90 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1caa0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1cab0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1cac0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1cad0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1cae0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1caf0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1cb00 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1cb10 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1cb20 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1cb30 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1cb40 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1cb50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1cb60 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1cb70 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1cb80 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1cb90 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1cba0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1cbb0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1cbc0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1cbd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1cbe0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1cbf0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1cc00 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1cc10 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1cc20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1cc30 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1cc40 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1cc50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1cc60 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1cc70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1cc80 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
1cc90 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
1cca0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1ccb0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1ccc0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1ccd0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1cce0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1ccf0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1cd00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1cd10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1cd20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd30 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1cd40 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1cd50 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1cd60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1cd70 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1cd80 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1cd90 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1cda0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1cdb0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1cdc0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1cdd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1cde0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1cdf0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1ce00 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
1ce10 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
1ce20 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1ce30 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1ce40 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1ce50 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
1ce60 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
1ce70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
1ce80 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
1ce90 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1cea0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1ceb0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
1cec0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
1ced0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1cee0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
1cef0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
1cf00 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
1cf10 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1cf20 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1cf30 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1cf40 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
1cf50 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1cf60 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1cf70 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1cf80 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1cf90 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1cfa0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1cfb0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
1cfc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1cfd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1cfe0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
1cff0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
1d000 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
1d010 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1d020 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
1d030 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
1d040 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
1d050 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1d060 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
1d070 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
1d080 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
1d090 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
1d0a0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
1d0b0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
1d0c0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
1d0d0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1d0e0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1d0f0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1d100 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1d110 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1d120 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1d130 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1d140 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1d150 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1d160 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1d170 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1d180 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1d190 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1d1a0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
1d1b0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1d1c0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1d1d0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1d1e0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1d1f0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1d200 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1d210 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1d220 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1d230 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1d240 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1d250 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1d260 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1d270 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1d280 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1d290 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1d2a0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1d2b0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1d2c0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1d2d0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1d2e0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1d2f0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1d300 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1d310 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1d320 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1d330 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1d340 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1d350 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1d360 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1d370 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1d380 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1d390 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1d3a0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1d3b0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1d3c0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1d3d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1d3e0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1d3f0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1d400 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1d410 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1d420 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
1d430 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
1d440 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
1d450 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
1d460 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1d470 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
1d480 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
1d490 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
1d4a0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
1d4b0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1d4c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1d4d0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
1d4e0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
1d4f0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1d500 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
1d510 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
1d520 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1d530 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
1d540 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1d550 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1d560 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
1d570 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
1d580 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
1d590 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
1d5a0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
1d5b0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
1d5c0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  dl>.** ^(<dt>SQL
1d5d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1d5e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d5f0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
1d600 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
1d610 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
1d620 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
1d630 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d640 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1d650 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1d660 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1d670 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1d680 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
1d690 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
1d6a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d6b0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1d6c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d6d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1d6e0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1d6f0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1d700 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1d710 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1d720 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1d730 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d740 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1d750 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1d760 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1d770 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
1d780 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d790 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1d7a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1d7b0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1d7c0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1d7d0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1d7e0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
1d7f0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1d800 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1d810 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
1d820 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d830 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
1d840 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
1d850 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
1d860 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1d880 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
1d890 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d8a0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
1d8b0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
1d8c0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
1d8d0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
1d8e0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
1d8f0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
1d900 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
1d910 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
1d920 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
1d930 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
1d940 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
1d950 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
1d960 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d970 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d980 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1d990 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d9a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d9b0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1d9c0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1d9d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d9e0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1d9f0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1da00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1da10 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1da20 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1da30 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1da40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1da50 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1da60 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1da70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1da80 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1da90 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1daa0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1dab0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1dac0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1dad0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1dae0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1daf0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1db00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
1db10 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
1db20 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
1db30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1db40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  .)^.**.** ^(<dt>
1db50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1db60 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1db70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1db80 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1db90 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1dba0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1dbb0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1dbc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1dbd0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1dbe0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1dbf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1dc00 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1dc10 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1dc20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1dc30 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1dc40 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1dc50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1dc60 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1dc70 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1dc80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1dc90 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1dca0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1dcb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1dcc0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1dcd0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1dce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1dcf0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1dd00 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1dd10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1dd20 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1dd30 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1dd40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1dd50 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1dd60 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1dd70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1dd80 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1dd90 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1dda0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ddb0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1ddc0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1ddd0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1dde0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1ddf0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1de00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1de10 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1de20 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1de30 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1de40 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1de50 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1de60 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1de70 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1de80 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1de90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1dea0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1deb0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1dec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ded0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1dee0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1def0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1df00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1df10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1df20 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1df30 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1df40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1df50 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1df60 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1df70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1df80 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1df90 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1dfa0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1dfb0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1dfc0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1dfd0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1dfe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1dff0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1e000 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1e010 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1e020 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1e030 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1e040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e050 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1e060 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1e070 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1e080 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1e090 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1e0a0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1e0b0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1e0c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1e0d0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1e0e0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1e0f0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1e100 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1e110 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1e120 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1e130 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1e140 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1e150 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1e160 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1e170 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1e180 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1e190 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1e1a0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1e1b0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1e1c0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1e1d0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1e1e0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1e1f0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1e200 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1e210 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1e220 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1e230 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1e240 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1e250 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1e260 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1e270 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1e280 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1e290 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1e2a0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1e2b0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1e2c0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1e2d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1e2e0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1e2f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1e300 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1e310 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1e320 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1e330 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1e340 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1e350 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1e360 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1e370 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1e380 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1e390 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1e3a0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1e3b0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1e3c0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1e3d0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1e3e0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1e3f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1e400 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1e410 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1e420 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1e430 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1e440 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1e450 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1e460 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1e470 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1e480 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1e490 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1e4a0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1e4b0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1e4c0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1e4d0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1e4e0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1e4f0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1e500 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1e510 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1e520 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1e530 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1e540 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1e550 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1e560 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1e570 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1e580 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1e590 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e5a0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1e5b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1e5c0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1e5d0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1e5e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1e5f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1e600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e610 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1e620 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1e630 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1e640 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1e650 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1e660 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1e670 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1e680 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1e690 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1e6a0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1e6b0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1e6c0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1e6d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1e6e0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1e6f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1e700 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1e710 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1e720 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1e730 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1e740 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1e750 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1e760 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1e770 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1e780 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1e790 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1e7a0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1e7b0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1e7c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1e7d0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1e7e0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1e7f0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1e800 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1e810 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1e820 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e830 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1e840 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1e850 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1e860 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1e870 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
1e880 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1e890 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
1e8a0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
1e8b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1e8c0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
1e8d0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
1e8e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1e8f0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1e900 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
1e910 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
1e920 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
1e930 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
1e940 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
1e950 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
1e960 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
1e970 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
1e980 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
1e990 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
1e9a0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
1e9b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
1e9c0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
1e9d0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
1e9e0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
1e9f0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
1ea00 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
1ea10 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1ea20 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
1ea30 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
1ea40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1ea50 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
1ea60 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1ea70 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
1ea80 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
1ea90 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1eaa0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1eab0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
1eac0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
1ead0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
1eae0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
1eaf0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
1eb00 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
1eb10 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
1eb20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1eb30 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
1eb40 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
1eb50 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1eb60 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
1eb70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1eb80 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1eb90 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
1eba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1ebb0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
1ebc0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
1ebd0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
1ebe0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
1ebf0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
1ec00 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
1ec10 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
1ec20 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
1ec30 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
1ec40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1ec50 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
1ec60 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
1ec70 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
1ec80 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
1ec90 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
1eca0 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
1ecb0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
1ecc0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
1ecd0 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65  E_STAT2] compile
1ece0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
1ecf0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
1ed00 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1ed10 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
1ed20 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
1ed30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ed40 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1ed50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ed60 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1ed70 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1ed80 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1ed90 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1eda0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1edb0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1edc0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1edd0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1ede0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1edf0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1ee00 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1ee10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1ee20 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1ee30 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1ee40 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1ee50 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1ee60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ee70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1ee80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1ee90 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1eea0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1eeb0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1eec0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1eed0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1eee0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1eef0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1ef00 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ef10 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1ef20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1ef30 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1ef40 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1ef50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ef60 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1ef70 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1ef80 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1ef90 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1efa0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1efb0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
1efc0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1efd0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1efe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1eff0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1f000 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1f010 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1f020 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1f030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f040 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1f050 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1f060 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1f070 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1f080 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1f090 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f0a0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1f0b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1f0c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1f0d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1f0e0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1f0f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
1f100 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f110 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f120 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f130 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1f140 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f150 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1f160 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1f170 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1f180 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1f190 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1f1a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1f1b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1f1c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1f1d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1f1e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1f1f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1f200 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1f210 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1f220 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
1f230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f240 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1f250 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
1f260 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f270 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
1f280 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
1f290 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
1f2a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
1f2b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
1f2c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f2d0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
1f2e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
1f2f0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1f300 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1f310 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
1f320 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f330 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
1f340 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1f350 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1f360 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1f370 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1f380 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1f390 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
1f3a0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
1f3b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
1f3c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
1f3d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1f3e0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
1f3f0 29 20 69 66 20 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  ) if .** and onl
1f400 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
1f410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
1f420 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
1f430 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
1f440 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
1f450 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
1f460 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1f470 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1f480 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1f490 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
1f4a0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
1f4b0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
1f4c0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
1f4d0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
1f4e0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
1f4f0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
1f500 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
1f510 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
1f520 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
1f530 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
1f540 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
1f550 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
1f560 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
1f570 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
1f580 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
1f590 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
1f5a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f5b0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
1f5c0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
1f5d0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
1f5e0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
1f5f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f600 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
1f610 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1f620 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
1f630 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
1f640 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
1f650 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
1f660 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
1f670 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
1f680 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
1f690 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
1f6a0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
1f6b0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
1f6c0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
1f6d0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
1f6e0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
1f6f0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
1f700 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
1f710 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
1f720 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
1f730 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
1f740 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
1f750 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
1f760 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
1f770 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
1f780 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
1f790 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
1f7a0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
1f7b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
1f7c0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
1f7d0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
1f7e0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
1f7f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
1f800 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
1f810 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
1f820 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
1f830 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
1f840 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
1f850 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
1f860 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
1f870 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
1f880 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
1f890 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
1f8a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
1f8b0 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
1f8c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
1f8d0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
1f8e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1f8f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
1f900 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
1f910 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
1f920 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1f930 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f940 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1f950 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1f960 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1f970 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1f980 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1f990 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1f9a0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1f9b0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1f9c0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1f9d0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1f9e0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1f9f0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1fa00 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
1fa10 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
1fa20 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
1fa30 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
1fa40 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1fa50 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
1fa60 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
1fa70 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
1fa80 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
1fa90 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
1faa0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
1fab0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
1fac0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
1fad0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
1fae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1faf0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
1fb00 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
1fb10 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
1fb20 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
1fb30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1fb40 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
1fb50 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
1fb60 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
1fb70 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
1fb80 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
1fb90 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1fba0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1fbb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1fbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1fbd0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1fbe0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1fbf0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1fc00 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1fc10 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1fc20 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1fc30 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1fc40 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1fc50 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1fc60 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1fc70 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1fc80 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1fc90 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1fca0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1fcb0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1fcc0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1fcd0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
1fce0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
1fcf0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
1fd00 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
1fd10 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
1fd20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
1fd30 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
1fd40 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
1fd50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
1fd60 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
1fd70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1fd80 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
1fd90 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
1fda0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1fdb0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
1fdc0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
1fdd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fde0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
1fdf0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
1fe00 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
1fe10 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
1fe20 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
1fe30 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
1fe40 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
1fe50 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
1fe60 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
1fe70 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1fe80 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1fe90 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1fea0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1feb0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
1fec0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
1fed0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
1fee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fef0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1ff00 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1ff10 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1ff20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1ff30 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1ff40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1ff50 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1ff60 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
1ff70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ff80 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
1ff90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ffa0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
1ffb0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
1ffc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ffd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
1ffe0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
1fff0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
20000 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
20010 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
20020 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
20030 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
20040 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
20050 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
20060 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
20070 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
20080 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20090 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
200a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
200b0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
200c0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
200d0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
200e0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
200f0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
20100 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
20110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
20120 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
20130 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
20140 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
20150 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
20160 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
20170 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
20180 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
20190 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
201a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
201b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
201c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
201d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
201e0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
201f0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
20200 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
20210 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
20220 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
20230 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
20240 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
20250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
20260 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
20270 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
20280 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
20290 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
202a0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
202b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
202c0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
202d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
202e0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
202f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
20300 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
20310 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
20320 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
20330 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
20340 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
20350 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
20360 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
20370 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
20380 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20390 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
203a0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
203b0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
203c0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
203d0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
203e0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
203f0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
20400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
20410 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
20420 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
20430 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
20440 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
20450 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
20460 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
20470 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
20480 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
20490 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
204a0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
204b0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
204c0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
204d0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
204e0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
204f0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
20500 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
20510 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
20520 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
20530 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
20540 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
20550 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
20560 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
20570 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
20580 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
20590 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
205a0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
205b0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
205c0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
205d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
205e0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
205f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
20600 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
20610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20620 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
20630 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
20640 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20650 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
20660 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
20670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20680 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
20690 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
206a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
206b0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
206c0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
206d0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
206e0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
206f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
20700 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
20710 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
20720 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
20730 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
20740 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
20750 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
20760 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
20770 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
20780 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
20790 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
207a0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
207b0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
207c0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
207d0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
207e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
207f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20800 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
20810 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
20820 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
20830 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
20840 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
20850 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
20860 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
20870 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
20880 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
20890 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
208a0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
208b0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
208c0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
208d0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
208e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
208f0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
20900 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
20910 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
20920 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
20930 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
20940 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
20950 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
20960 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
20970 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
20980 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
20990 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
209a0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
209b0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
209c0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
209d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
209e0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
209f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
20a00 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
20a10 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
20a20 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
20a30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
20a40 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
20a50 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
20a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
20a70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
20a80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
20a90 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
20aa0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
20ab0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20ac0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
20ad0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
20ae0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
20af0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
20b00 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
20b10 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
20b20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
20b30 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
20b40 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
20b50 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
20b60 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
20b70 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
20b80 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
20b90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
20ba0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
20bb0 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
20bc0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
20bd0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
20be0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
20bf0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
20c00 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
20c10 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
20c20 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
20c30 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
20c40 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
20c50 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
20c60 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
20c70 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
20c80 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
20c90 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
20ca0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
20cb0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
20cc0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
20cd0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
20ce0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
20cf0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
20d00 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
20d10 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
20d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20d30 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
20d40 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
20d50 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
20d60 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
20d70 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
20d80 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
20d90 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
20da0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
20db0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
20dc0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
20dd0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
20de0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
20df0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
20e00 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
20e10 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
20e20 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
20e30 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
20e40 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
20e50 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
20e60 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
20e70 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
20e80 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
20e90 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
20ea0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
20eb0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
20ec0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
20ed0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
20ee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
20ef0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
20f00 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
20f10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
20f20 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
20f30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
20f40 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
20f50 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
20f60 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
20f70 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
20f80 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
20f90 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
20fa0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
20fb0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
20fc0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
20fd0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
20fe0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
20ff0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
21000 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
21010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21020 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
21030 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
21040 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
21050 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
21060 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
21070 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
21080 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
21090 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
210a0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
210b0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
210c0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
210d0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
210e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
210f0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
21100 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
21110 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
21120 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
21130 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
21140 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
21150 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
21160 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
21170 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
21180 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
21190 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
211a0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
211b0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
211c0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
211d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
211e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
211f0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
21200 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21210 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
21220 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21230 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21240 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21250 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
21260 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
21270 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
21280 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
21290 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
212a0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
212b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
212c0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
212d0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
212e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
212f0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
21300 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
21310 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21320 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
21330 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
21340 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
21350 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
21360 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
21370 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
21380 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
21390 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
213a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
213b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
213c0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
213d0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
213e0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
213f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
21400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
21410 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
21420 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
21430 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
21440 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
21450 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
21460 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
21470 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
21480 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
21490 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
214a0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
214b0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
214c0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
214d0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
214e0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
214f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21500 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
21510 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
21520 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
21530 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
21540 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
21550 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
21560 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
21570 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
21580 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
21590 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
215a0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
215b0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
215c0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
215d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
215e0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
215f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
21600 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
21610 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
21620 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
21630 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
21640 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
21650 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
21660 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
21670 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
21680 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
21690 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
216a0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
216b0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
216c0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
216d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
216e0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
216f0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
21700 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21710 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
21720 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
21730 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21740 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
21750 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21760 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
21770 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
21780 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
21790 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
217a0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
217b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
217c0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
217d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
217e0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
217f0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
21800 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
21810 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21820 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
21830 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
21840 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
21850 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
21860 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
21870 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
21880 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
21890 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
218a0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
218b0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
218c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
218d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
218e0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
218f0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
21900 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
21910 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
21920 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
21930 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
21940 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
21950 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
21960 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
21970 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
21980 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
21990 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
219a0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
219b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
219c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
219d0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
219e0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
219f0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
21a00 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
21a10 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
21a20 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
21a30 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
21a40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
21a50 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
21a60 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
21a70 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
21a80 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
21a90 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
21aa0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
21ab0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
21ac0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
21ad0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
21ae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21af0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
21b00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
21b10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21b20 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
21b30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
21b40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
21b50 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
21b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21b70 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21b80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
21b90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21ba0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
21bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
21bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21bd0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
21be0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
21bf0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
21c00 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
21c10 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
21c20 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
21c30 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
21c40 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
21c50 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
21c60 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
21c70 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
21c80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
21c90 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
21ca0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
21cb0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
21cc0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
21cd0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
21ce0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
21cf0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
21d00 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
21d10 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
21d20 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
21d30 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
21d40 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
21d50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
21d60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21d70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21d80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21d90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21da0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21db0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21dc0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
21dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21de0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21df0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
21e00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21e10 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
21e20 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
21e30 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
21e40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
21e50 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
21e60 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
21e70 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
21e80 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
21e90 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
21ea0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21eb0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
21ec0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
21ed0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
21ee0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
21ef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21f00 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
21f10 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
21f20 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
21f30 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
21f40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
21f50 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
21f60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
21f70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
21f80 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
21f90 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
21fa0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
21fb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
21fc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
21fd0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
21fe0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
21ff0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
22000 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
22010 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
22020 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
22030 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
22040 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
22050 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
22060 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
22070 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22080 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
22090 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
220a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
220b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
220c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
220d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
220e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
220f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
22100 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22110 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
22120 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
22130 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
22140 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
22150 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
22160 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
22170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
22180 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
22190 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
221a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
221b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
221c0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
221d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
221e0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
221f0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
22200 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
22210 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
22220 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
22230 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
22240 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
22250 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
22260 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
22270 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
22280 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
22290 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
222a0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
222b0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
222c0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
222d0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
222e0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
222f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
22300 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
22310 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
22320 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
22330 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22340 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
22350 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
22360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22370 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
22380 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
22390 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
223a0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
223b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
223c0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
223d0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
223e0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
223f0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
22400 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
22410 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
22420 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
22430 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
22440 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
22450 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
22460 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
22470 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
22480 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
22490 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
224a0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
224b0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
224c0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
224d0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
224e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
224f0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
22500 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
22510 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
22520 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
22530 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
22540 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
22550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22560 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
22570 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
22580 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
22590 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
225a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
225b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
225c0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
225d0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
225e0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
225f0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
22600 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
22610 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
22620 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
22630 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
22640 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
22650 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
22660 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
22670 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
22680 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
22690 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
226a0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
226b0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
226c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
226d0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
226e0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
226f0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
22700 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
22710 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
22720 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
22730 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
22740 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
22750 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
22760 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
22770 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
22780 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
22790 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
227a0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
227b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
227c0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
227d0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
227e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
227f0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
22800 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
22810 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
22820 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
22830 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
22840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
22850 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
22860 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
22870 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
22880 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22890 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
228a0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
228b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
228c0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
228d0 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
228e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
228f0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
22900 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
22910 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
22920 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
22930 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
22940 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
22950 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
22960 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
22970 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
22980 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
22990 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
229a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
229b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
229c0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
229d0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
229e0 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
229f0 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
22a00 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
22a10 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
22a20 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
22a30 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
22a40 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
22a50 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
22a60 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
22a70 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
22a80 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
22a90 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
22aa0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
22ab0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
22ac0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
22ad0 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
22ae0 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
22af0 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
22b00 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
22b10 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
22b20 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
22b30 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
22b40 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
22b50 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
22b60 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
22b70 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
22b80 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
22b90 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
22ba0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
22bb0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
22bc0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
22bd0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
22be0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
22bf0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
22c00 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
22c10 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
22c20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
22c30 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
22c40 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
22c50 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
22c60 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
22c70 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
22c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
22c90 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
22ca0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
22cb0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
22cc0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
22cd0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
22ce0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
22cf0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
22d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22d10 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
22d20 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
22d30 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
22d40 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
22d50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22d60 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
22d70 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
22d80 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
22d90 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
22da0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
22db0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
22dc0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
22dd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22de0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
22df0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22e00 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
22e10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
22e20 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
22e30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22e40 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
22e50 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
22e60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22e70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
22e80 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
22e90 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
22ea0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22eb0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
22ec0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22ed0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
22ee0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22ef0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
22f00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22f20 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
22f30 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
22f40 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
22f50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22f60 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
22f70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
22f80 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
22f90 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
22fa0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
22fb0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
22fc0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
22fd0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
22fe0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
22ff0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
23000 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
23010 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
23020 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
23030 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
23040 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
23050 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
23060 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
23070 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
23080 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
23090 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
230a0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
230b0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
230c0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
230d0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
230e0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
230f0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
23100 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
23110 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
23120 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
23130 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
23140 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
23150 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
23160 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
23170 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
23180 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
23190 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
231a0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
231b0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
231c0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
231d0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
231e0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
231f0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
23200 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
23210 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
23220 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
23230 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
23240 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
23250 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
23260 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
23270 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
23280 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
23290 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
232a0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
232b0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
232c0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
232d0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
232e0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
232f0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
23300 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
23310 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
23320 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
23330 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
23340 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
23350 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
23360 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
23370 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
23380 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
23390 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
233a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
233b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
233c0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
233d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
233e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
233f0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
23400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23410 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
23420 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
23430 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
23440 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
23450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23460 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
23470 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
23480 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
23490 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
234a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
234b0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
234c0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
234d0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
234e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
234f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
23500 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
23510 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
23520 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
23530 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
23540 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
23550 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
23560 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
23570 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
23580 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
23590 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
235a0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
235b0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
235c0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
235d0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
235e0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
235f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23600 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
23610 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
23620 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
23630 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
23640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23650 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23660 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
23670 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
23680 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
23690 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
236a0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
236b0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
236c0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
236d0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
236e0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
236f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
23700 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
23710 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
23720 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
23730 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
23740 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
23750 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
23760 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
23770 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
23780 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
23790 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
237a0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
237b0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
237c0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
237d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
237e0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
237f0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
23800 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
23810 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
23820 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
23830 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
23840 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
23850 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
23860 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
23870 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
23880 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
23890 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
238a0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
238b0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
238c0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
238d0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
238e0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
238f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
23900 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
23910 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
23920 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
23930 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
23940 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
23950 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
23960 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
23970 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
23980 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
23990 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
239a0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
239b0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
239c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
239d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
239e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
239f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
23a00 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
23a10 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
23a20 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
23a30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
23a40 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
23a50 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
23a60 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
23a70 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
23a80 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
23a90 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
23aa0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
23ab0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
23ac0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
23ad0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
23ae0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
23af0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
23b00 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
23b10 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
23b20 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
23b30 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
23b40 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
23b50 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
23b60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
23b70 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
23b80 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
23b90 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
23ba0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
23bb0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
23bc0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
23bd0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
23be0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
23bf0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
23c00 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
23c10 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
23c20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
23c30 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
23c40 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
23c50 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
23c60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
23c70 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
23c80 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
23c90 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
23ca0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
23cb0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
23cc0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
23cd0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
23ce0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
23cf0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
23d00 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
23d10 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
23d20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
23d30 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
23d40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23d50 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
23d60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
23d70 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
23d80 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
23d90 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
23da0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
23db0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
23dc0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
23dd0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
23de0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
23df0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
23e00 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
23e10 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
23e20 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
23e30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
23e40 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
23e50 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
23e60 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
23e70 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
23e80 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
23e90 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
23ea0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
23eb0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
23ec0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
23ed0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
23ee0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
23ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
23f00 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
23f10 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
23f20 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
23f30 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
23f40 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
23f50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23f60 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
23f70 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
23f80 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
23f90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23fa0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
23fb0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
23fc0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
23fd0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
23fe0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
23ff0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
24000 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
24010 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
24020 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
24030 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
24040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
24050 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
24060 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
24070 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
24080 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
24090 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
240a0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
240b0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
240c0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
240d0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
240e0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
240f0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
24100 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
24110 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
24120 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
24130 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
24140 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
24150 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
24160 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
24170 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
24180 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
24190 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
241a0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
241b0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
241c0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
241d0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
241e0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
241f0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
24200 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
24210 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
24220 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
24230 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
24240 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
24250 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
24260 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
24270 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
24280 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
24290 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
242a0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
242b0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
242c0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
242d0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
242e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
242f0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
24300 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
24310 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
24320 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
24330 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24340 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
24350 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
24360 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
24370 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
24380 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
24390 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
243a0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
243b0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
243c0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
243d0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
243e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
243f0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
24400 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
24410 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
24420 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
24430 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
24440 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
24450 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
24460 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
24470 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
24480 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
24490 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
244a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
244b0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
244c0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
244d0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
244e0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
244f0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
24500 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
24510 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
24520 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24530 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
24540 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24550 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
24560 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
24570 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
24580 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
24590 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
245a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
245b0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
245c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
245d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
245e0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
245f0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
24600 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
24610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24620 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
24630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
24640 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
24650 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
24660 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
24670 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
24680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
24690 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
246a0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
246b0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
246c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
246d0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
246e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
246f0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
24700 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
24710 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
24720 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
24730 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24740 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
24750 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
24760 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
24770 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24790 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
247a0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
247b0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
247c0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
247d0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
247e0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
247f0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
24800 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
24810 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
24820 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24830 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
24840 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
24850 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
24860 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
24870 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
24880 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
24890 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
248a0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
248b0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
248c0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
248d0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
248e0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
248f0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
24900 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
24910 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
24920 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
24930 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
24940 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
24950 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
24960 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
24970 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
24980 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
24990 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
249a0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
249b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
249c0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
249d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
249e0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
249f0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
24a00 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
24a10 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
24a20 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
24a30 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
24a40 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
24a50 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
24a60 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
24a70 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
24a80 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
24a90 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
24aa0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
24ab0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
24ac0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
24ad0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
24ae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
24af0 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
24b00 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
24b10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
24b20 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
24b30 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
24b40 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
24b50 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
24b60 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
24b70 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
24b80 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
24b90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
24ba0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
24bb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24bc0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
24bd0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
24be0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
24bf0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
24c00 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
24c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24c20 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
24c30 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
24c40 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
24c50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
24c60 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
24c70 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
24c80 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
24c90 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
24ca0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
24cb0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
24cc0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
24cd0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
24ce0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
24cf0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
24d00 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
24d10 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
24d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
24d30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
24d40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
24d50 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
24d60 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
24d70 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
24d80 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
24d90 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
24da0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
24db0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
24dc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
24dd0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
24de0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
24df0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
24e00 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
24e10 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
24e20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
24e30 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
24e40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
24e50 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
24e60 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
24e70 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
24e80 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
24e90 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24ea0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
24eb0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
24ec0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
24ed0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
24ee0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
24ef0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
24f00 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
24f10 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
24f20 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
24f30 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
24f40 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
24f50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
24f60 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
24f70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24f80 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
24f90 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
24fa0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
24fb0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
24fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
24fd0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
24fe0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
24ff0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
25000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25010 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
25020 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
25030 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
25040 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
25050 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
25060 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
25070 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
25080 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
25090 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
250a0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
250b0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
250c0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
250d0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
250e0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
250f0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
25100 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
25110 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
25120 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
25130 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
25140 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
25150 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
25160 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
25170 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
25180 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
25190 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
251a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
251b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
251c0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
251d0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
251e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
251f0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
25200 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
25210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
25220 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
25230 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
25240 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
25250 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
25260 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
25270 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
25280 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25290 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
252a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
252b0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
252c0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
252d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
252e0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
252f0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
25300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25310 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
25320 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
25330 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
25340 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
25350 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
25360 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
25370 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
25380 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
25390 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
253a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
253b0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
253c0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
253d0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
253e0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
253f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25400 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
25410 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
25420 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
25430 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
25440 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
25450 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
25460 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
25470 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
25480 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
25490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
254a0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
254b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
254c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
254d0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
254e0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
254f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
25500 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
25510 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
25520 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
25530 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
25540 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
25550 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
25560 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25570 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
25580 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
25590 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
255a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
255b0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
255c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
255d0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
255e0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
255f0 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
25600 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
25610 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
25620 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
25630 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25640 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
25650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25660 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
25670 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
25680 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
25690 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
256a0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
256b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
256c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
256d0 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
256e0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
256f0 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
25700 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
25710 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
25720 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
25730 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
25740 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
25750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
25760 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
25770 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
25780 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
25790 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
257a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
257b0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
257c0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
257d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
257e0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
257f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25800 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
25810 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
25820 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
25830 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
25840 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
25850 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
25860 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
25870 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
25880 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
25890 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
258a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
258b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
258c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
258d0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
258e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
258f0 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
25900 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25910 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
25920 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
25930 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
25940 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
25950 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
25960 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
25970 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
25980 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25990 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
259a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
259b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
259c0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
259d0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
259e0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
259f0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
25a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
25a10 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
25a20 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
25a30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
25a40 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
25a50 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
25a60 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
25a70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
25a80 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
25a90 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
25aa0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
25ab0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
25ac0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
25ad0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
25ae0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
25af0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
25b00 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
25b10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
25b20 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
25b30 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
25b40 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
25b50 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
25b60 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
25b70 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
25b80 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
25b90 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
25ba0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
25bb0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
25bc0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
25bd0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
25be0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
25bf0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
25c00 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
25c10 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
25c20 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
25c30 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
25c40 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
25c50 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
25c60 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
25c70 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
25c80 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
25c90 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
25ca0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
25cb0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
25cc0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
25cd0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
25ce0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
25cf0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
25d00 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
25d10 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
25d20 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
25d30 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
25d40 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
25d50 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
25d60 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
25d70 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
25d80 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
25d90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
25da0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
25db0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
25dc0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
25dd0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
25de0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
25df0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
25e00 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
25e10 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
25e20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
25e30 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
25e40 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
25e50 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
25e60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
25e70 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
25e80 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
25e90 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
25ea0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
25eb0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
25ec0 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
25ed0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
25ee0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
25ef0 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
25f00 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
25f10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
25f20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
25f30 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
25f40 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
25f50 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
25f60 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
25f70 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
25f80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
25f90 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
25fa0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
25fb0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
25fc0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
25fd0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
25fe0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
25ff0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
26000 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
26010 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
26020 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
26030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
26040 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
26050 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
26060 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
26070 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
26080 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
26090 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
260a0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
260b0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
260c0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
260d0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
260e0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
260f0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
26100 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
26110 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
26120 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
26130 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
26140 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
26150 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
26160 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
26170 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
26180 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
26190 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
261a0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
261b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
261c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
261d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
261e0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
261f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26200 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
26210 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
26220 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
26230 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
26240 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
26250 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
26260 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
26270 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
26280 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
26290 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
262a0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
262b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
262c0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
262d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
262e0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
262f0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
26300 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
26310 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
26320 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
26330 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
26340 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
26350 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
26360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26370 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
26380 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
26390 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
263a0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
263b0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
263c0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
263d0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
263e0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
263f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
26400 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
26410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26420 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
26430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26440 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
26450 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
26460 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
26470 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
26480 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
26490 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
264a0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
264b0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
264c0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
264d0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
264e0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
264f0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
26500 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
26510 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
26520 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
26530 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
26540 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
26550 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
26560 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
26570 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
26580 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
26590 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
265a0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
265b0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
265c0 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
265d0 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
265e0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
265f0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
26600 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
26610 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
26620 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
26630 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
26640 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
26650 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
26660 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
26670 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
26680 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
26690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
266a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
266b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
266c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
266d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
266e0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
266f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
26700 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
26710 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
26720 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
26730 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
26740 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
26750 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
26760 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
26770 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
26780 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
26790 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
267a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
267b0 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
267c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
267d0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
267e0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
267f0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
26800 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
26810 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
26820 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
26830 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
26840 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
26850 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
26860 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
26870 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
26880 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
26890 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
268a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
268b0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
268c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
268d0 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
268e0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
268f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
26900 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
26910 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
26920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26930 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
26940 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
26950 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
26960 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
26970 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
26980 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
26990 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
269a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
269b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
269c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
269d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
269e0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
269f0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
26a00 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
26a10 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
26a20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
26a30 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
26a40 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
26a50 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
26a60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
26a70 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
26a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
26a90 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
26aa0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
26ab0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
26ac0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
26ad0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
26ae0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
26af0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
26b00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26b10 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
26b20 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
26b30 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
26b40 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
26b50 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
26b60 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
26b70 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
26b80 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
26b90 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
26ba0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26bb0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
26bc0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
26bd0 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
26be0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
26c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26c10 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
26c20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26c30 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
26c40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
26c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26c60 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
26c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
26c80 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
26c90 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
26ca0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26cb0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
26cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
26cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26ce0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
26cf0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
26d00 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
26d10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26d20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
26d30 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
26d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
26d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26d60 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
26d70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26d80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
26d90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
26da0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
26db0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
26dc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26dd0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
26de0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
26df0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
26e00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
26e10 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
26e20 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
26e30 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26e40 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
26e50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
26e60 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
26e70 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
26e80 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
26e90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
26ea0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
26eb0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
26ec0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
26ed0 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
26ee0 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72 20  errors or.** or 
26ef0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
26f00 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
26f10 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
26f20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26f30 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
26f40 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
26f50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
26f60 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
26f70 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
26f80 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
26f90 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
26fa0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
26fb0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
26fc0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
26fd0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
26fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26ff0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
27000 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
27010 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
27020 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
27030 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
27040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27050 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
27060 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
27070 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
27080 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
27090 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
270a0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
270b0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
270c0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
270d0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
270e0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
270f0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
27100 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
27110 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
27120 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
27130 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
27140 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
27150 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
27160 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
27170 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
27180 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
27190 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
271a0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
271b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
271c0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
271d0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
271e0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
271f0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
27200 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
27210 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
27220 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
27230 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
27240 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
27250 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
27260 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
27270 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
27280 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
27290 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
272a0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
272b0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
272c0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
272d0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
272e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
272f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27310 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
27320 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
27330 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
27340 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
27350 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
27360 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
27370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27380 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
27390 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
273a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
273b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
273c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
273d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
273e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
273f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
27400 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
27410 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
27420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
27430 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
27440 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
27450 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
27460 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
27470 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
27480 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
27490 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
274a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
274b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
274c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
274d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
274e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
274f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
27500 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
27510 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
27520 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
27530 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27540 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
27550 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
27560 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
27570 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
27580 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27590 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
275a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
275b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
275c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
275d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
275e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
275f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
27600 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
27610 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
27620 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
27630 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
27640 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
27650 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
27660 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
27670 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
27680 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
27690 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
276a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
276b0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
276c0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
276d0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
276e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
276f0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
27700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27710 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
27720 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
27730 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
27740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27750 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
27760 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
27770 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
27780 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
27790 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
277a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
277b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
277c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
277d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
277e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
277f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
27800 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
27810 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
27820 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
27830 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
27840 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
27850 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
27860 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
27870 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
27880 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
27890 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
278a0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
278b0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
278c0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
278d0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
278e0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
278f0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
27900 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
27910 20 66 6f 72 0a 2a 2a 20 74 68 65 20 74 68 65 20   for.** the the 
27920 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
27930 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
27940 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
27950 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
27960 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
27970 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
27980 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
27990 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
279a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
279b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
279c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
279d0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
279e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
279f0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
27a00 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
27a10 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
27a20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
27a30 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
27a40 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
27a50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
27a60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27a70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27a80 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
27a90 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
27aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
27ab0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
27ac0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
27ad0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
27ae0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
27af0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
27b00 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
27b10 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
27b20 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
27b30 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
27b40 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
27b50 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
27b60 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
27b70 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
27b80 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
27b90 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
27ba0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
27bb0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
27bc0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
27bd0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
27be0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
27bf0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
27c00 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
27c10 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
27c20 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
27c30 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
27c40 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27c50 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
27c60 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
27c70 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
27c80 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
27c90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27ca0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
27cb0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
27cc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
27cd0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
27ce0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
27cf0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
27d00 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
27d10 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
27d20 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
27d30 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
27d40 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
27d50 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
27d60 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
27d70 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
27d80 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
27d90 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
27da0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
27db0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
27dc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27dd0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
27de0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
27df0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
27e00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
27e10 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
27e20 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
27e30 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
27e40 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
27e50 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
27e60 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
27e70 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
27e80 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
27e90 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
27ea0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
27eb0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
27ec0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
27ed0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
27ee0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
27ef0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
27f00 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
27f10 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
27f20 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
27f30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
27f40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27f50 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
27f60 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
27f70 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
27f80 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
27f90 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
27fa0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
27fb0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
27fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
27fd0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
27fe0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
27ff0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
28000 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
28010 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
28020 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
28030 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
28040 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
28050 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
28060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
28070 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
28080 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
28090 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
280a0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
280b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
280c0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
280d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
280e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
280f0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
28100 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
28110 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
28120 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
28130 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
28140 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
28150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
28160 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
28170 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
28180 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
28190 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
281a0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
281b0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
281c0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
281d0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
281e0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
281f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28200 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
28210 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
28220 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
28230 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
28240 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
28250 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
28260 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
28270 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
28280 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
28290 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
282a0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
282b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
282c0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
282d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
282e0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
282f0 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
28300 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
28310 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
28320 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
28330 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
28340 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
28350 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 65   pass NULL poine
28360 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
28370 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
28380 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
28390 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
283a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
283b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
283c0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
283d0 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
283e0 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
283f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28400 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
28410 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
28420 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
28430 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
28440 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
28450 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
28460 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
28470 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
28480 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
28490 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
284a0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
284b0 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
284c0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
284d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
284e0 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
284f0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
28500 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
28510 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
28520 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
28530 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
28540 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
28550 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
28560 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
28570 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
28580 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
28590 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
285a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
285b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
285c0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
285d0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
285e0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
285f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28600 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
28610 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
28620 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
28630 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
28640 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
28650 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
28660 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
28670 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
28680 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
28690 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
286a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
286b0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
286c0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
286d0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
286e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
286f0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
28700 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
28710 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
28720 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
28730 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
28740 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
28750 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
28760 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
28770 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
28780 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
28790 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
287a0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
287b0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
287c0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
287d0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
287e0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
287f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
28800 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
28810 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
28820 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
28830 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
28840 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
28850 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
28860 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
28870 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
28880 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
28890 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
288a0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
288b0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
288c0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
288d0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
288e0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
288f0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
28900 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28910 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
28920 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
28930 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28940 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
28950 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
28960 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
28970 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
28980 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
28990 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
289a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
289b0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
289c0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
289d0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
289e0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
289f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
28a00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28a10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28a20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
28a30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
28a40 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
28a50 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
28a60 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
28a70 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
28a80 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
28a90 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
28aa0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
28ab0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
28ac0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28ad0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
28ae0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
28af0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
28b00 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
28b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28b20 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
28b30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
28b40 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
28b50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
28b60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
28b70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
28b80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
28b90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28ba0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
28bb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
28bc0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
28bd0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
28be0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
28bf0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
28c00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28c10 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
28c20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28c30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
28c40 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
28c50 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
28c60 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
28c70 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
28c80 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
28c90 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
28ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
28cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
28cc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
28cd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
28ce0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
28cf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
28d00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
28d10 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
28d20 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
28d30 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
28d40 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
28d50 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
28d60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
28d70 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
28d80 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
28d90 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
28da0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
28db0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
28dc0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
28dd0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
28de0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
28df0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
28e00 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
28e10 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
28e20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
28e30 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
28e40 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
28e50 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
28e60 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
28e70 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
28e80 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
28e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28ea0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
28eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
28ec0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
28ed0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
28ee0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
28ef0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
28f00 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
28f10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
28f20 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
28f30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
28f40 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
28f50 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
28f60 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
28f70 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
28f80 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
28f90 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
28fa0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
28fb0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
28fc0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
28fd0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
28fe0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
28ff0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
29000 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
29010 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
29020 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
29030 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
29040 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
29050 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
29060 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
29070 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
29080 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
29090 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
290a0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
290b0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
290c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
290d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
290e0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
290f0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
29100 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
29110 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
29120 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
29130 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
29140 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
29150 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
29160 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29170 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
29180 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
29190 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
291a0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
291b0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
291c0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
291d0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
291e0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
291f0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
29200 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
29210 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
29220 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
29230 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
29240 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
29250 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
29260 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
29270 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
29280 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
29290 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
292a0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
292b0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
292c0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
292d0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
292e0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
292f0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
29300 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
29310 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
29320 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
29330 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
29340 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
29350 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
29360 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29370 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
29380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29390 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
293a0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
293b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
293c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
293d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
293e0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
293f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
29400 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
29410 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
29420 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
29430 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29440 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
29450 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
29460 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29470 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
29480 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
29490 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
294a0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
294b0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
294c0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
294d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
294e0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
294f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
29500 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
29510 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29520 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
29530 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
29540 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
29550 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
29560 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29570 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
29580 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
29590 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
295a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
295b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
295c0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
295d0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
295e0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
295f0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
29600 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
29610 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
29620 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
29630 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29640 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
29650 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
29660 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
29670 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
29680 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
29690 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
296a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
296b0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
296c0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
296d0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
296e0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
296f0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
29700 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
29710 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
29720 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
29730 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
29740 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
29750 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
29760 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
29770 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
29780 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
29790 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
297a0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
297b0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
297c0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
297d0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
297e0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
297f0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
29800 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
29810 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
29820 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
29830 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
29840 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
29850 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
29860 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
29870 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
29880 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
29890 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
298a0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
298b0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
298c0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
298d0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
298e0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
298f0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
29900 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
29910 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
29920 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
29930 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
29940 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
29950 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
29960 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
29970 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
29980 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
29990 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
299a0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
299b0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
299c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
299d0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
299e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
299f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
29a00 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
29a10 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
29a20 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
29a30 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
29a40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
29a50 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
29a60 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
29a70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29a80 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
29a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29aa0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
29ab0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
29ac0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
29ad0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
29ae0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
29af0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
29b00 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
29b10 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
29b20 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
29b30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
29b40 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
29b50 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
29b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
29b70 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
29b80 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
29b90 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
29ba0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
29bb0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
29bc0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
29bd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
29be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
29bf0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
29c00 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
29c10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
29c20 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
29c30 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
29c40 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
29c50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
29c60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
29c70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29c80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
29c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29ca0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29cb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29cc0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
29cd0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
29ce0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29cf0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
29d00 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
29d10 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
29d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29d30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
29d40 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
29d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29d70 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
29d80 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
29d90 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
29da0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
29db0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
29dc0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
29dd0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
29de0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
29df0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
29e00 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
29e10 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
29e20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29e30 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
29e40 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
29e50 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
29e60 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
29e70 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
29e80 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
29e90 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
29ea0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
29eb0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
29ec0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
29ed0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
29ee0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
29ef0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
29f00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
29f10 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
29f20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
29f30 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
29f40 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
29f50 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
29f60 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
29f70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29f80 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
29f90 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
29fa0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
29fb0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
29fc0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
29fd0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
29fe0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
29ff0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
2a000 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
2a010 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
2a020 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
2a030 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
2a040 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
2a050 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2a060 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
2a070 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
2a080 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
2a090 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
2a0a0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
2a0b0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
2a0c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2a0d0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
2a0e0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
2a0f0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
2a100 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
2a110 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
2a120 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
2a130 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2a140 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
2a150 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2a160 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
2a170 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
2a180 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
2a190 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2a1a0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
2a1b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
2a1c0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
2a1d0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
2a1e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2a1f0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
2a200 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2a210 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
2a220 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
2a230 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
2a240 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
2a250 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
2a260 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2a270 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2a280 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
2a290 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
2a2a0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
2a2b0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
2a2c0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
2a2d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
2a2e0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
2a2f0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
2a300 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
2a310 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
2a320 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2a330 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
2a340 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
2a350 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
2a360 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2a370 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
2a380 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2a390 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2a3a0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2a3b0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2a3c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2a3d0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
2a3e0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
2a3f0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2a400 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2a410 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
2a420 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2a430 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
2a440 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2a450 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2a460 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2a470 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
2a480 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2a490 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2a4a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2a4b0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2a4c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2a4d0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2a4e0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2a4f0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
2a500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a510 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2a520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a530 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2a540 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2a550 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2a560 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2a570 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2a580 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2a590 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a5a0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2a5b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a5c0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2a5d0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2a5e0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2a5f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a600 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2a610 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2a620 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2a630 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2a640 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2a650 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2a660 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2a670 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2a680 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2a690 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
2a6a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2a6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a6c0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2a6d0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
2a6e0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
2a6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2a700 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
2a710 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2a720 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2a730 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
2a740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a750 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
2a760 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2a770 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a780 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2a790 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2a7a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2a7b0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2a7c0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2a7d0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2a7e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2a7f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
2a800 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2a810 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2a820 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a830 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a840 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2a850 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
2a860 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2a870 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2a880 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2a890 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2a8a0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2a8b0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2a8c0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2a8d0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2a8e0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2a8f0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2a900 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2a910 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2a920 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2a930 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2a940 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2a950 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2a960 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2a970 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2a980 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2a990 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2a9a0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2a9b0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2a9c0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2a9d0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2a9e0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2a9f0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2aa00 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2aa10 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2aa20 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2aa30 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2aa40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2aa50 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2aa60 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2aa70 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2aa80 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2aa90 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2aaa0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2aab0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2aac0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2aad0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2aae0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2aaf0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2ab00 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2ab10 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2ab20 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2ab30 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2ab40 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2ab50 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2ab60 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2ab70 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2ab80 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2ab90 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2aba0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2abb0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2abc0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2abd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2abe0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
2abf0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2ac00 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2ac10 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2ac20 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2ac30 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2ac40 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2ac50 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2ac60 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2ac70 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2ac80 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2ac90 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2aca0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2acb0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2acc0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2acd0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
2ace0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2acf0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
2ad00 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
2ad10 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
2ad20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2ad30 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
2ad40 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2ad50 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2ad60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ad70 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2ad80 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2ad90 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2ada0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2adb0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2adc0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2add0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
2ade0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
2adf0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2ae00 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2ae10 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
2ae20 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
2ae30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2ae40 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
2ae50 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
2ae60 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
2ae70 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2ae80 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
2ae90 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
2aea0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
2aeb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
2aec0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
2aed0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
2aee0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
2aef0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
2af00 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
2af10 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
2af20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
2af30 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2af40 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
2af50 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
2af60 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
2af70 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2af80 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2af90 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
2afa0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
2afb0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
2afc0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
2afd0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2afe0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2aff0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2b000 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2b010 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2b020 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2b030 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2b040 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
2b050 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
2b060 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2b070 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2b080 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2b090 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2b0a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2b0b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2b0c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2b0d0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2b0e0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
2b0f0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
2b100 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2b110 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
2b120 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
2b130 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
2b140 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
2b150 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
2b160 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
2b170 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
2b180 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2b190 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
2b1a0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
2b1b0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
2b1c0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
2b1d0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
2b1e0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2b1f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
2b200 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
2b210 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
2b220 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
2b230 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
2b240 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
2b250 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
2b260 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
2b270 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
2b280 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2b290 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
2b2a0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
2b2b0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
2b2c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2b2d0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
2b2e0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
2b2f0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
2b300 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
2b310 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
2b320 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2b330 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
2b340 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
2b350 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
2b360 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
2b370 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
2b380 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
2b390 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
2b3a0 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
2b3b0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
2b3c0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
2b3d0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2b3e0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
2b3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
2b400 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
2b410 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2b420 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
2b430 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
2b440 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2b450 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
2b460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b470 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
2b480 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
2b490 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
2b4a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2b4b0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
2b4c0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2b4d0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
2b4e0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
2b4f0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2b500 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
2b510 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b520 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2b530 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b540 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
2b550 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2b560 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2b570 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
2b580 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
2b590 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
2b5a0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
2b5b0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
2b5c0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
2b5d0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
2b5e0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
2b5f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
2b600 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
2b610 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2b620 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2b630 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2b640 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2b650 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2b660 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
2b670 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2b680 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2b690 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b6a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b6b0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
2b6c0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
2b6d0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
2b6e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2b6f0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
2b700 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
2b710 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
2b720 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2b730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b740 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2b750 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
2b760 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
2b770 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2b780 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b790 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
2b7a0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
2b7b0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
2b7c0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
2b7d0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
2b7e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2b7f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2b800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b810 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2b820 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2b830 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2b840 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2b850 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2b860 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2b870 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2b880 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2b890 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2b8a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2b8b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b8c0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2b8d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b8e0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
2b8f0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
2b900 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
2b910 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
2b920 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
2b930 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2b940 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
2b950 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
2b960 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
2b970 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b980 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
2b990 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2b9a0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
2b9b0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2b9c0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
2b9d0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
2b9e0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
2b9f0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2ba00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2ba10 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
2ba20 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2ba30 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2ba40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ba50 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
2ba60 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
2ba70 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
2ba80 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2ba90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2baa0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2bab0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2bac0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2bad0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2bae0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
2baf0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2bb00 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
2bb10 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2bb20 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2bb30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2bb40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2bb50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2bb60 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
2bb70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2bb80 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
2bb90 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2bba0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
2bbb0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
2bbc0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
2bbd0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2bbe0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
2bbf0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
2bc00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2bc10 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2bc20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2bc30 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2bc40 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
2bc50 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
2bc60 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
2bc70 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
2bc80 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
2bc90 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2bca0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
2bcb0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
2bcc0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
2bcd0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
2bce0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
2bcf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2bd00 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2bd10 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2bd20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2bd30 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2bd40 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2bd50 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2bd60 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
2bd70 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
2bd80 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
2bd90 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
2bda0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
2bdb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2bdc0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2bdd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bde0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
2bdf0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
2be00 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
2be10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2be20 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2be30 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2be40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2be50 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2be60 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2be70 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2be80 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
2be90 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
2bea0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2beb0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
2bec0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
2bed0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
2bee0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
2bef0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
2bf00 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2bf10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2bf20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2bf30 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2bf40 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2bf50 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2bf60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bf70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2bf80 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
2bf90 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2bfa0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2bfb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2bfc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2bfd0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2bfe0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2bff0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2c000 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2c010 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c020 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2c030 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c040 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2c050 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2c060 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2c070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c080 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
2c090 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2c0a0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2c0b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c0c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c0d0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
2c0e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2c0f0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2c100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2c110 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
2c120 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2c130 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2c140 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2c150 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2c160 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2c170 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2c180 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c190 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2c1a0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2c1b0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2c1c0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2c1d0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2c1e0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2c1f0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2c200 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2c210 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2c220 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
2c230 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2c240 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2c250 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2c260 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2c270 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2c280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2c290 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2c2a0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2c2b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2c2c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c2d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2c2e0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2c2f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2c300 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
2c310 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2c320 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
2c330 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2c340 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
2c350 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2c360 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2c370 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2c380 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2c390 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
2c3a0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
2c3b0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2c3c0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
2c3d0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2c3e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2c3f0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
2c400 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c410 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
2c420 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2c430 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2c440 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2c450 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2c460 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2c470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2c480 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
2c490 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2c4a0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
2c4b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
2c4c0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
2c4d0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
2c4e0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
2c4f0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
2c500 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
2c510 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2c520 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2c530 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2c540 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2c550 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
2c560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2c570 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2c580 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2c590 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
2c5a0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
2c5b0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
2c5c0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
2c5d0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
2c5e0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
2c5f0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
2c600 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
2c610 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
2c620 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
2c630 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
2c640 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2c650 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2c660 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2c670 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2c680 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2c690 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2c6a0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2c6b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2c6c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2c6d0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
2c6e0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
2c6f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
2c700 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
2c710 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
2c720 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
2c730 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2c740 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
2c750 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2c760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c770 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2c780 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2c790 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2c7a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c7b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2c7c0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2c7d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c7e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c7f0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2c800 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2c810 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2c820 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2c830 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2c840 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2c850 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2c860 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
2c870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2c880 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2c890 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2c8a0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2c8b0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2c8c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2c8d0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2c8e0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2c8f0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
2c900 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c910 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2c920 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2c930 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2c940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c950 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2c960 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2c970 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2c980 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2c990 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2c9a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2c9b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2c9c0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2c9d0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2c9e0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2c9f0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
2ca00 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2ca10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ca20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ca30 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2ca40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2ca50 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2ca60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ca70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
2ca80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ca90 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2caa0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2cab0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2cac0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2cad0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cae0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2caf0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2cb00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cb10 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2cb20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2cb30 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2cb40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2cb50 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2cb60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2cb70 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2cb80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cb90 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2cba0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2cbb0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2cbc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2cbd0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2cbe0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2cbf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2cc00 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2cc10 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2cc20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2cc30 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2cc40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2cc50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2cc60 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2cc70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2cc80 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2cc90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cca0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2ccb0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2ccc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ccd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cce0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2ccf0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2cd00 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2cd10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2cd20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cd30 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2cd40 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2cd50 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2cd60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2cd70 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2cd80 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2cd90 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2cda0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2cdb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2cdc0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2cdd0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2cde0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2cdf0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2ce00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2ce10 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2ce20 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2ce30 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2ce40 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2ce50 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2ce60 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2ce70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2ce80 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2ce90 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
2cea0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2ceb0 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
2cec0 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
2ced0 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
2cee0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
2cef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cf00 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
2cf10 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2cf20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2cf30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2cf40 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
2cf50 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
2cf60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2cf70 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
2cf80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2cf90 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
2cfa0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
2cfb0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
2cfc0 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
2cfd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2cfe0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
2cff0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
2d000 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
2d010 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
2d020 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
2d030 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
2d040 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
2d050 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
2d060 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
2d070 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
2d080 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
2d090 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
2d0a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
2d0b0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
2d0c0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2d0d0 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
2d0e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2d0f0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
2d100 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
2d110 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2d120 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
2d130 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
2d140 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
2d150 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
2d160 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
2d170 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
2d180 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
2d190 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2d1a0 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
2d1b0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
2d1c0 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
2d1d0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
2d1e0 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
2d1f0 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
2d200 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
2d210 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
2d220 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
2d230 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2d240 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
2d250 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
2d260 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
2d270 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
2d280 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
2d290 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2d2a0 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
2d2b0 20 69 73 20 61 20 61 70 70 6c 69 63 61 74 69 6f   is a applicatio
2d2c0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
2d2d0 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
2d2e0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
2d2f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2d300 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
2d310 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2d320 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
2d330 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
2d340 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
2d350 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
2d360 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
2d370 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
2d380 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2d390 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
2d3a0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
2d3b0 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
2d3c0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
2d3d0 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
2d3e0 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
2d3f0 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
2d400 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
2d410 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
2d420 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
2d430 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
2d440 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
2d450 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
2d460 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
2d470 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2d480 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
2d490 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
2d4a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
2d4b0 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
2d4c0 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
2d4d0 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
2d4e0 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
2d4f0 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
2d500 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2d510 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
2d520 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
2d530 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
2d540 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
2d550 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
2d560 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
2d570 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
2d580 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
2d590 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
2d5a0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
2d5b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d5c0 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
2d5d0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
2d5e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
2d5f0 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
2d600 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
2d610 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2d620 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
2d630 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2d640 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
2d650 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
2d660 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d670 6e 20 6d 75 73 74 20 61 6c 77 61 79 20 72 65 74  n must alway ret
2d680 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
2d690 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
2d6a0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
2d6b0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
2d6c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2d6d0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
2d6e0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2d6f0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
2d700 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
2d710 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
2d720 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
2d730 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
2d740 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
2d750 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
2d760 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
2d770 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
2d780 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
2d790 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
2d7a0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
2d7b0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
2d7c0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
2d7d0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2d7e0 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
2d7f0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
2d800 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
2d810 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
2d820 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
2d830 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
2d840 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
2d850 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
2d860 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
2d870 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
2d880 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
2d890 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
2d8a0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
2d8b0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
2d8c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
2d8d0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
2d8e0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
2d8f0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
2d900 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2d910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d920 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d930 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
2d940 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
2d950 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
2d960 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
2d970 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
2d980 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
2d990 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
2d9a0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
2d9b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d9c0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
2d9d0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
2d9e0 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
2d9f0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
2da00 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
2da10 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
2da20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
2da30 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
2da40 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
2da50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2da60 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
2da70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2da80 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
2da90 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
2daa0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
2dab0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
2dac0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
2dad0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2dae0 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
2daf0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
2db00 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
2db10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2db20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2db30 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
2db40 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
2db50 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
2db60 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
2db70 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
2db80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2db90 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
2dba0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
2dbb0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
2dbc0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
2dbd0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
2dbe0 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
2dbf0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
2dc00 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
2dc10 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
2dc20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
2dc30 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
2dc40 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
2dc50 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
2dc60 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
2dc70 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
2dc80 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
2dc90 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
2dca0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2dcb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dcc0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2dcd0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
2dce0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dcf0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
2dd00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2dd10 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2dd20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2dd30 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
2dd40 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2dd50 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2dd60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2dd70 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2dd80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2dd90 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
2dda0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2ddb0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2ddc0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2ddd0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
2dde0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2ddf0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2de00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
2de10 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2de20 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
2de30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2de40 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
2de50 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2de60 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
2de70 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2de80 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2de90 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2dea0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2deb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2dec0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2ded0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2dee0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2def0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2df00 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2df10 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2df20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2df30 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2df40 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2df50 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2df60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2df70 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2df80 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2df90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2dfa0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2dfb0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2dfc0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2dfd0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2dfe0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2dff0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2e000 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2e010 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2e020 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2e030 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2e040 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2e050 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2e060 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2e070 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2e080 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2e090 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2e0a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2e0b0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2e0c0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2e0d0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2e0e0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2e0f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2e100 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2e110 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2e120 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2e130 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2e140 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2e150 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2e160 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2e170 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2e180 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2e190 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2e1a0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2e1b0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2e1c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2e1d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2e1e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2e1f0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2e200 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e210 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2e220 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2e230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2e240 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2e250 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2e260 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2e270 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2e280 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2e290 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2e2a0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2e2b0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2e2c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2e2d0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2e2e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2e2f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2e300 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2e310 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2e320 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2e330 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2e340 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2e350 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2e360 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2e370 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e380 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2e390 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e3a0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2e3b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e3c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2e3d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2e3e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2e3f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2e400 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2e410 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2e420 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2e430 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2e440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2e450 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2e460 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2e470 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2e480 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2e490 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2e4a0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2e4b0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2e4c0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2e4d0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2e4e0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2e4f0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2e500 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2e510 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2e520 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2e530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2e540 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2e550 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2e560 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2e570 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2e580 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2e590 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2e5a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2e5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e5c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2e5d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2e5e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2e5f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2e600 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2e610 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2e620 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2e630 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2e640 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2e650 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2e660 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2e670 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2e680 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2e690 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2e6a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2e6b0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2e6c0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2e6d0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2e6e0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2e6f0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2e700 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2e710 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2e720 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2e730 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e740 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e750 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2e760 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2e770 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2e780 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2e790 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2e7a0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2e7b0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2e7c0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2e7d0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2e7e0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2e7f0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2e800 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2e810 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2e820 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2e830 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2e840 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2e850 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2e860 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2e870 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2e880 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2e890 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2e8a0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2e8b0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2e8c0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2e8d0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2e8e0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2e8f0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2e900 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2e910 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2e920 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2e930 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2e940 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2e950 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2e960 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2e970 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2e980 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2e990 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
2e9a0 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
2e9b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
2e9c0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
2e9d0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
2e9e0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
2e9f0 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
2ea00 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2ea10 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
2ea20 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
2ea30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
2ea40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2ea50 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2ea60 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2ea70 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
2ea80 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
2ea90 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
2eaa0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
2eab0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
2eac0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
2ead0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2eae0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2eaf0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2eb00 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2eb10 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2eb20 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2eb30 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2eb40 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2eb50 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2eb60 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2eb70 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2eb80 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2eb90 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
2eba0 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
2ebb0 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
2ebc0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
2ebd0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
2ebe0 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
2ebf0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
2ec00 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
2ec10 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2ec20 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
2ec30 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
2ec40 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
2ec50 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
2ec60 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
2ec70 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
2ec80 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
2ec90 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2eca0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
2ecb0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
2ecc0 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
2ecd0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
2ece0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
2ecf0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
2ed00 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
2ed10 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
2ed20 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
2ed30 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2ed40 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2ed50 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2ed60 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
2ed70 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
2ed80 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
2ed90 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
2eda0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
2edb0 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
2edc0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
2edd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2ede0 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
2edf0 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
2ee00 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
2ee10 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
2ee20 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
2ee30 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
2ee40 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2ee50 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2ee60 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
2ee70 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
2ee80 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
2ee90 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2eea0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2eeb0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
2eec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2eed0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
2eee0 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
2eef0 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
2ef00 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
2ef10 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
2ef20 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2ef30 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
2ef40 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
2ef50 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
2ef60 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
2ef70 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
2ef80 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
2ef90 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2efa0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
2efb0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
2efc0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
2efd0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
2efe0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2eff0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2f000 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
2f010 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
2f020 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
2f030 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2f040 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2f050 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
2f060 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
2f070 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2f080 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2f090 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
2f0a0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
2f0b0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
2f0c0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
2f0d0 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
2f0e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
2f0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
2f100 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
2f110 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
2f120 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
2f130 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
2f140 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
2f150 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
2f160 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
2f170 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
2f180 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
2f190 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
2f1a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2f1b0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2f1c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2f1d0 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
2f1e0 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
2f1f0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2f200 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2f210 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
2f220 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  d..*/.SQLITE_EXT
2f230 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
2f240 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
2f250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f260 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
2f270 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
2f280 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
2f290 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
2f2a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2f2b0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
2f2c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f2d0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
2f2e0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
2f2f0 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
2f300 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
2f310 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
2f320 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
2f330 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
2f340 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
2f350 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
2f360 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2f370 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2f380 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
2f390 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
2f3a0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
2f3b0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
2f3c0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
2f3d0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
2f3e0 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
2f3f0 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
2f400 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
2f410 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
2f420 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
2f430 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
2f440 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
2f450 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
2f460 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
2f470 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
2f480 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
2f490 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
2f4a0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
2f4b0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
2f4c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
2f4d0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
2f4e0 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
2f4f0 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
2f500 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
2f510 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
2f520 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
2f530 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
2f540 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
2f550 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f560 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
2f570 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
2f580 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
2f590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2f5a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
2f5b0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
2f5c0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
2f5d0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
2f5e0 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
2f5f0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2f600 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2f610 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
2f620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2f630 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
2f640 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
2f650 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2f660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f670 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
2f680 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2f690 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f6a0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
2f6b0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
2f6c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f6d0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
2f6e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f6f0 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
2f700 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
2f710 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
2f720 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2f730 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
2f740 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
2f750 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
2f760 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
2f770 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
2f780 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
2f790 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
2f7a0 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
2f7b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
2f7c0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
2f7d0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2f7e0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
2f7f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2f800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
2f810 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
2f820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2f830 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2f840 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2f850 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
2f860 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2f870 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
2f880 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
2f890 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2f8a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f8b0 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
2f8c0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
2f8d0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
2f8e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f8f0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
2f900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f910 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
2f920 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
2f930 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
2f940 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
2f950 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
2f960 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
2f970 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
2f980 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
2f990 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
2f9a0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
2f9b0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
2f9c0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
2f9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
2f9e0 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
2f9f0 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
2fa00 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
2fa10 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
2fa20 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
2fa30 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
2fa40 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
2fa50 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
2fa60 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
2fa70 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
2fa80 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2fa90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2faa0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
2fab0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
2fac0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2fad0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2fae0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
2faf0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2fb00 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2fb10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2fb20 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2fb30 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2fb40 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
2fb50 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
2fb60 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2fb70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2fb80 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2fb90 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2fba0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2fbb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2fbc0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
2fbd0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2fbe0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
2fbf0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2fc00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2fc10 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2fc20 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2fc30 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
2fc40 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
2fc50 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
2fc60 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2fc70 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2fc80 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2fc90 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
2fca0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2fcb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2fcc0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
2fcd0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
2fce0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
2fcf0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
2fd00 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
2fd10 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
2fd20 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
2fd30 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
2fd40 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
2fd50 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
2fd60 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
2fd70 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
2fd80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2fd90 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
2fda0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2fdb0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
2fdc0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
2fdd0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
2fde0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
2fdf0 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
2fe00 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
2fe10 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2fe20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2fe30 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
2fe40 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
2fe50 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
2fe60 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
2fe70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
2fe80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2fe90 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2fea0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2feb0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2fec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2fed0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
2fee0 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
2fef0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2ff00 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2ff10 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2ff20 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2ff30 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2ff40 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2ff50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ff60 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2ff70 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
2ff80 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
2ff90 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
2ffa0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
2ffb0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2ffc0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2ffd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ffe0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2fff0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
30000 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
30010 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
30020 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
30030 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
30040 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
30050 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
30060 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
30070 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
30080 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
30090 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
300a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
300b0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
300c0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
300d0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
300e0 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
300f0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
30100 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
30110 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
30120 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
30130 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
30140 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
30150 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
30160 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
30170 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
30180 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
30190 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
301a0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
301b0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
301c0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
301d0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
301e0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
301f0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
30200 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
30210 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
30220 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
30230 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
30240 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
30250 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
30260 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
30270 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
30280 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
30290 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
302a0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
302b0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
302c0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
302d0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
302e0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
302f0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
30300 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
30310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30320 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
30330 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
30340 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30350 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
30360 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
30370 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
30380 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
30390 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
303a0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
303b0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
303c0 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
303d0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
303e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
303f0 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
30400 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
30410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30420 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
30430 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
30440 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
30450 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
30460 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
30480 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
30490 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
304a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
304b0 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
304c0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
304d0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
304e0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
304f0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
30500 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
30510 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
30520 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
30530 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
30540 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rridden..**.** ^
30550 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
30560 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
30570 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
30580 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
30590 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
305a0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
305b0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68   deleted..** ^Th
305c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
305d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
305e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
305f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
30600 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
30610 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
30620 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c   ^The second cal
30630 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
30640 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
30650 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
30660 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
30670 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
30680 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
30690 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
306a0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
306b0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
306c0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
306d0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
306e0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
306f0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
30700 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
30710 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
30720 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
30730 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
30740 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54  ected row..** ^T
30750 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
30760 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
30770 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
30780 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68  e row..** ^In th
30790 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
307a0 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
307b0 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74   [rowid] after t
307c0 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
307d0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  place..**.** ^(T
307e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
307f0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
30800 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
30810 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
30820 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
30830 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
30840 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
30850 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  e).)^.**.** ^In 
30860 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
30870 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20  ementation, the 
30880 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
30890 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
308a0 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72  en duplication r
308b0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
308c0 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a  because of an.**
308d0 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20   [ON CONFLICT | 
308e0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c  ON CONFLICT REPL
308f0 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e  ACE] clause.  ^N
30900 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65  or is the update
30910 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64   hook.** invoked
30920 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64   when rows are d
30930 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65  eleted using the
30940 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
30950 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  ization]..** The
30960 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69   exceptions defi
30970 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61  ned in this para
30980 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e  graph might chan
30990 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
309a0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
309b0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ite..**.** The u
309c0 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65  pdate hook imple
309d0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
309e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
309f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
30a00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
30a10 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
30a20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61  invoked the upda
30a30 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63  te hook.  Any ac
30a40 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
30a50 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
30a60 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
30a70 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
30a80 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
30a90 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
30aa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
30ab0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
30ac0 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65  gered the update
30ad0 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74   hook..** Note t
30ae0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
30af0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
30b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30b10 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
30b20 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
30b30 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
30b40 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
30b50 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
30b60 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
30b70 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
30b80 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  te_hook(D,C,P) f
30b90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72  unction.** retur
30ba0 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  ns the P argumen
30bb0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
30bc0 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74  ous call.** on t
30bd0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
30be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
30bf0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
30c00 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f  the first call o
30c10 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  n D..**.** See a
30c20 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
30c30 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
30c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  and [sqlite3_rol
30c50 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a  lback_hook()].**
30c60 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a   interfaces..*/.
30c70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
30c80 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
30c90 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
30ca0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
30cb0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
30cc0 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
30cd0 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
30ce0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30cf0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
30d00 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
30d10 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57  er Cache.** KEYW
30d20 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
30d30 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  che}.**.** ^(Thi
30d40 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
30d50 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
30d60 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
30d70 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
30d80 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
30d90 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
30da0 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20  tween [database 
30db0 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e  connection | con
30dc0 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20  nections].** to 
30dd0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30de0 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  e. Sharing is en
30df0 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
30e00 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a  ument is true.**
30e10 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
30e20 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
30e30 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   false.)^.**.** 
30e40 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69  ^Cache sharing i
30e50 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
30e60 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e  sabled for an en
30e70 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  tire process..**
30e80 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67   This is a chang
30e90 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76  e as of SQLite v
30ea0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e  ersion 3.5.0. In
30eb0 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
30ec0 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68  of SQLite,.** sh
30ed0 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65  aring was enable
30ee0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
30ef0 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
30f00 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
30f10 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72  ^(The cache shar
30f20 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
30f30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
30f40 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
30f50 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
30f60 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
30f70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
30f80 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
30f90 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
30fa0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
30fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30fc0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
30fd0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
30fe0 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
30ff0 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
31000 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
31010 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ed.)^.**.** ^(Th
31020 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31030 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
31040 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
31050 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
31060 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73  sabled.** succes
31070 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
31080 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
31090 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29  rned otherwise.)
310a0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20  ^.**.** ^Shared 
310b0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
310c0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
310d0 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
310e0 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
310f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
31100 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
31110 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
31120 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
31130 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
31140 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
31150 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  tly..**.** See A
31160 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
31170 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
31180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31190 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
311a0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
311b0 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
311c0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
311d0 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
311e0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
311f0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
31200 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
31210 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
31220 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
31230 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
31240 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
31250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
31260 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
31270 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
31280 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
31290 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
312a0 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
312b0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
312c0 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
312d0 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
312e0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
312f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
31300 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
31310 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31320 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
31330 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
31340 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
31350 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
31360 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
31370 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
31380 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
31390 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
313a0 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
313b0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
313c0 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
313d0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
313e0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
313f0 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  T]..*/.int sqlit
31400 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
31410 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
31420 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
31430 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
31440 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  Size.**.** ^The 
31450 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
31460 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65  p_limit64() inte
31470 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f  rface sets and/o
31480 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a  r queries the.**
31490 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74   soft limit on t
314a0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
314b0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
314c0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
314d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51  y SQLite..** ^SQ
314e0 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20  Lite strives to 
314f0 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79  keep heap memory
31500 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c   utilization bel
31510 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ow the soft heap
31520 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64  .** limit by red
31530 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  ucing the number
31540 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69   of pages held i
31550 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  n the page cache
31560 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f  .** as heap memo
31570 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61  ry usages approa
31580 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a  ches the limit..
31590 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61  ** ^The soft hea
315a0 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74  p limit is "soft
315b0 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74  " because even t
315c0 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72  hough SQLite str
315d0 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20  ives to stay.** 
315e0 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c  below the limit,
315f0 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20   it will exceed 
31600 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72  the limit rather
31610 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a   than generate.*
31620 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  * an [SQLITE_NOM
31630 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f  EM] error.  In o
31640 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
31650 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31660 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20  .** is advisory 
31670 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
31680 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
31690 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  om sqlite3_soft_
316a0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69  heap_limit64() i
316b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
316c0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
316d0 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68  imit prior to th
316e0 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65  e call.  ^If the
316f0 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e   argument N is n
31700 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20  egative.** then 
31710 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64  no change is mad
31720 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65  e to the soft he
31730 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65  ap limit.  Hence
31740 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  , the current.**
31750 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66   size of the sof
31760 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
31770 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62   be determined b
31780 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  y invoking.** sq
31790 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
317a0 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61  limit64() with a
317b0 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65   negative argume
317c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  nt..**.** ^If th
317d0 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
317e0 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f  zero then the so
317f0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
31800 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
31810 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70   ^(The soft heap
31820 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e   limit is not en
31830 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75  forced in the cu
31840 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
31850 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f  tion.** if one o
31860 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77  r more of follow
31870 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61  ing conditions a
31880 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c  re true:.**.** <
31890 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
318a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
318b0 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a  is set to zero..
318c0 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61  ** <li> Memory a
318d0 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73  ccounting is dis
318e0 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f  abled using a co
318f0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
31900 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
31910 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
31920 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
31930 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74  US],...) start-t
31940 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a  ime option and.*
31950 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49  *      the [SQLI
31960 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
31970 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ATUS] compile-ti
31980 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c  me option..** <l
31990 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76  i> An alternativ
319a0 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  e page cache imp
319b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73  lementation is s
319c0 70 65 63 69 66 65 64 20 75 73 69 6e 67 0a 2a 2a  pecifed using.**
319d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
319e0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
319f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e  ONFIG_PCACHE],..
31a00 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  .)..** <li> The 
31a10 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63  page cache alloc
31a20 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77  ates from its ow
31a30 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75  n memory pool su
31a40 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62  pplied.**      b
31a50 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  y [sqlite3_confi
31a60 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
31a70 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e  G_PAGECACHE],...
31a80 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ) rather than.**
31a90 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68        from the h
31aa0 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  eap..** </ul>)^.
31ab0 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20  **.** Beginning 
31ac0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
31ad0 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73  ion 3.7.3, the s
31ae0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
31af0 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65  s enforced.** re
31b00 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
31b10 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
31b20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
31b30 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
31b40 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
31b50 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b   option is invok
31b60 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54  ed.  With [SQLIT
31b70 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
31b80 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20  MANAGEMENT],.** 
31b90 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
31ba0 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20  mit is enforced 
31bb0 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20  on every memory 
31bc0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74  allocation.  Wit
31bd0 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hout.** [SQLITE_
31be0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
31bf0 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73  NAGEMENT], the s
31c00 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
31c10 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a  s only enforced.
31c20 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ** when memory i
31c30 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74  s allocated by t
31c40 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20  he page cache.  
31c50 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73  Testing suggests
31c60 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a   that because.**
31c70 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20   the page cache 
31c80 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61  is the predomina
31c90 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69  te memory user i
31ca0 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a  n SQLite, most.*
31cb0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  * applications w
31cc0 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71  ill achieve adeq
31cd0 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c  uate soft heap l
31ce0 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74  imit enforcement
31cf0 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20   without.** the 
31d00 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  use of [SQLITE_E
31d10 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
31d20 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
31d30 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  The circumstance
31d40 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51  s under which SQ
31d50 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63  Lite will enforc
31d60 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  e the soft heap 
31d70 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61  limit may.** cha
31d80 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  nges in future r
31d90 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
31da0 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  e..*/.sqlite3_in
31db0 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  t64 sqlite3_soft
31dc0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71  _heap_limit64(sq
31dd0 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a  lite3_int64 N);.
31de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31df0 20 44 65 70 72 65 63 61 74 65 64 20 53 6f 66 74   Deprecated Soft
31e00 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65   Heap Limit Inte
31e10 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41  rface.** DEPRECA
31e20 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TED.**.** This i
31e30 73 20 61 20 64 65 70 72 65 63 61 74 65 64 20 76  s a deprecated v
31e40 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  ersion of the [s
31e50 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
31e60 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69  _limit64()].** i
31e70 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69 73 20  nterface.  This 
31e80 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69  routine is provi
31e90 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
31ea0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
31eb0 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e  .** only.  All n
31ec0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
31ed0 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a  should use the.*
31ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  * [sqlite3_soft_
31ef0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20  heap_limit64()] 
31f00 69 6e 74 65 72 66 61 63 65 20 72 61 74 68 65 72  interface rather
31f10 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a   than this one..
31f20 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
31f30 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
31f40 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
31f50 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a  t(int N);.../*.*
31f60 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72  * CAPI3REF: Extr
31f70 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
31f80 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
31f90 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68   Table.**.** ^Th
31fa0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31fb0 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75  ns metadata abou
31fc0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
31fd0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
31fe0 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61  c.** database ta
31ff0 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
32000 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61  sing the [databa
32010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
32020 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20  andle.** passed 
32030 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
32040 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
32050 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d  **.** ^The colum
32060 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
32070 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
32080 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
32090 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a  parameters to.**
320a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
320b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
320c0 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
320d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
320e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
320f0 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
32100 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  , or an attached
32110 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
32120 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
32130 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
32140 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20  NULL. ^If it is 
32150 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
32160 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
32170 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
32180 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
32190 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
321a0 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79  lgorithm used by
321b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
321c0 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c  gine to.** resol
321d0 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74  ve unqualified t
321e0 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e  able references.
321f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
32200 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
32210 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
32220 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
32230 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
32240 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  n.** name of the
32250 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
32260 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
32270 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
32280 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61  parameters.** ma
32290 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
322a0 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65   ^Metadata is re
322b0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
322c0 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
322d0 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
322e0 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
322f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
32300 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
32310 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20   function. ^Any 
32320 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
32330 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
32340 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
32350 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
32360 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
32370 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
32380 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63  d..**.** ^(<bloc
32390 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
323a0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
323b0 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65   <tr><th> Parame
323c0 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c  ter <th> Output<
323d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65  br>Type <th>  De
323e0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  scription.**.** 
323f0 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64  <tr><td> 5th <td
32400 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
32410 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20  d> Data type.** 
32420 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64  <tr><td> 6th <td
32430 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
32440 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75  d> Name of defau
32450 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
32460 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  uence.** <tr><td
32470 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 7th <td> int  
32480 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
32490 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61   if column has a
324a0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
324b0 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  aint.** <tr><td>
324c0 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   8th <td> int   
324d0 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
324e0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  if column is par
324f0 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
32500 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   KEY.** <tr><td>
32510 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   9th <td> int   
32520 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
32530 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55  if column is [AU
32540 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20  TOINCREMENT].** 
32550 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
32560 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
32570 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  * ^The memory po
32580 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
32590 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
325a0 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
325b0 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  the.** declarati
325c0 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
325d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
325e0 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
325f0 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63  il the next.** c
32600 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74  all to any SQLit
32610 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
32620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
32630 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
32640 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
32650 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
32660 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
32670 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
32680 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
32690 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
326a0 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
326b0 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20   an.** [INTEGER 
326c0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
326d0 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
326e0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
326f0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
32700 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
32710 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
32720 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
32730 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66  red column. ^(If
32740 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
32750 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
32760 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49  red [INTEGER PRI
32770 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
32780 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
32790 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
327a0 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f  are set as follo
327b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
327c0 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
327d0 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
327e0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
327f0 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
32800 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
32810 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
32820 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
32830 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
32840 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  0.** </pre>)^.**
32850 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
32860 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
32870 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
32880 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
32890 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
328a0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
328b0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
328c0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
328d0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
328e0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
328f0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72  e found, an [err
32900 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
32910 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
32920 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a  r message left.*
32930 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * in the [databa
32940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
32950 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20  to be retrieved 
32960 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72  using sqlite3_er
32970 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a  rmsg()).)^.**.**
32980 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e   ^This API is on
32990 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
329a0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
329b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
329c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
329d0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
329e0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
329f0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
32a00 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
32a10 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
32a20 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
32a30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
32a40 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
32a50 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
32a60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
32a70 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
32a80 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
32a90 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
32aa0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
32ab0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
32ac0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
32ad0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
32ae0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
32af0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
32b00 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
32b10 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
32b20 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
32b30 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
32b40 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
32b50 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
32b60 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
32b70 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
32b80 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
32b90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
32ba0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
32bb0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
32bc0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
32bd0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
32be0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
32bf0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
32c00 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
32c10 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
32c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32c30 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
32c40 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
32c50 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
32c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32c70 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
32c80 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ion.**.** ^This 
32c90 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20  interface loads 
32ca0 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
32cb0 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d  ion library from
32cc0 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e   the named file.
32cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32ce0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
32cf0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  on() interface a
32d00 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20  ttempts to load 
32d10 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74  an.** SQLite ext
32d20 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63  ension library c
32d30 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20  ontained in the 
32d40 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a  file zFile..**.*
32d50 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69  * ^The entry poi
32d60 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20  nt is zProc..** 
32d70 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c  ^zProc may be 0,
32d80 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
32d90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
32da0 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65  ntry point.** de
32db0 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
32dc0 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
32dd0 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  t"..** ^The sqli
32de0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
32df0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  on() interface r
32e00 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
32e10 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
32e20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
32e30 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
32e40 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
32e50 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
32e60 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67  urs and pzErrMsg
32e70 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20   is not 0, then 
32e80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
32e90 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
32ea0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
32eb0 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  l attempt to.** 
32ec0 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
32ed0 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ith error messag
32ee0 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
32ef0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69   memory.** obtai
32f00 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
32f10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65  3_malloc()]. The
32f20 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
32f30 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65  n.** should free
32f40 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20   this memory by 
32f50 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
32f60 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
32f70 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
32f80 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c  ng must be enabl
32f90 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
32fa0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
32fb0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
32fc0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
32fd0 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65  his API,.** othe
32fe0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77  rwise an error w
32ff0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
33000 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
33010 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  the [load_extens
33020 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ion() SQL functi
33030 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  on]..*/.int sqli
33040 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
33050 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
33060 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
33070 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
33080 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
33090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
330a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
330b0 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
330c0 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
330d0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
330e0 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
330f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33100 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
33110 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
33120 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
33130 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
33140 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
33150 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
33160 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
33170 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
33180 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
33190 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69   Disable Extensi
331a0 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
331b0 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f   ^So as not to o
331c0 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c  pen security hol
331d0 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c  es in older appl
331e0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72  ications that ar
331f0 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20  e.** unprepared 
33200 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74  to deal with ext
33210 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20  ension loading, 
33220 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f  and as a means o
33230 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65  f disabling.** e
33240 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33250 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
33260 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  g user-entered S
33270 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  QL, the followin
33280 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76  g API.** is prov
33290 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65  ided to turn the
332a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
332b0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68  xtension()] mech
332c0 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66  anism on and off
332d0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
332e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66  on loading is of
332f0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65  f by default. Se
33300 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a  e ticket #1863..
33310 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c  ** ^Call the sql
33320 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
33330 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
33340 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d  tine with onoff=
33350 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78  =1.** to turn ex
33360 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
33370 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77  on and call it w
33380 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20  ith onoff==0 to 
33390 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20  turn.** it back 
333a0 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e  off again..*/.in
333b0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
333c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
333d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74  sqlite3 *db, int
333e0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
333f0 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61  CAPI3REF: Automa
33400 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61  tically Load Sta
33410 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45  tically Linked E
33420 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  xtensions.**.** 
33430 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
33440 63 61 75 73 65 73 20 74 68 65 20 78 45 6e 74 72  causes the xEntr
33450 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 69 6f  yPoint() functio
33460 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
33470 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20  for.** each new 
33480 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33490 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 63 72  tion] that is cr
334a0 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 65 61  eated.  The idea
334b0 20 68 65 72 65 20 69 73 20 74 68 61 74 0a 2a 2a   here is that.**
334c0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 69   xEntryPoint() i
334d0 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  s the entry poin
334e0 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 61 6c  t for a statical
334f0 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65  ly linked SQLite
33500 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68   extension.** th
33510 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 74 6f  at is to be auto
33520 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64  matically loaded
33530 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61   into all new da
33540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33550 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e  ns..**.** ^(Even
33560 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 6e 63   though the func
33570 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20 73  tion prototype s
33580 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 72 79  hows that xEntry
33590 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a  Point() takes.**
335a0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 6e   no arguments an
335b0 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 2c 20  d returns void, 
335c0 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 78  SQLite invokes x
335d0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 74  EntryPoint() wit
335e0 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d  h three.** argum
335f0 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 74 73  ents and expects
33600 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 65 73   and integer res
33610 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 73 69  ult as if the si
33620 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 0a 2a  gnature of the.*
33630 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 77 68  * entry point wh
33640 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ere as follows:.
33650 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
33660 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70  e><pre>.** &nbsp
33670 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 6f 69  ;  int xEntryPoi
33680 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  nt(.** &nbsp;   
33690 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a   sqlite3 *db,.**
336a0 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74   &nbsp;    const
336b0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
336c0 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63  ,.** &nbsp;    c
336d0 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
336e0 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
336f0 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73   *pThunk.** &nbs
33700 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  p;  );.** </pre>
33710 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
33720 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 45 6e  **.** If the xEn
33730 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65  tryPoint routine
33740 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20 65   encounters an e
33750 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64 20  rror, it should 
33760 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a  make *pzErrMsg.*
33770 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70  * point to an ap
33780 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
33790 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 6e 65  message (obtaine
337a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
337b0 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61  mprintf()]).** a
337c0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70  nd return an app
337d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
337e0 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20  code].  ^SQLite 
337f0 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a 70 7a  ensures that *pz
33800 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c  ErrMsg.** is NUL
33810 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  L before calling
33820 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
33830 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ().  ^SQLite wil
33840 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c  l invoke.** [sql
33850 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
33860 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 72 20  *pzErrMsg after 
33870 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65  xEntryPoint() re
33880 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a  turns.  ^If any.
33890 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  ** xEntryPoint()
338a0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
338b0 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  r, the [sqlite3_
338c0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
338d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
338e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
338f0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  _v2()] call that
33900 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 78 45   provoked the xE
33910 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c  ntryPoint() will
33920 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   fail..**.** ^Ca
33930 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 61 75  lling sqlite3_au
33940 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29 20  to_extension(X) 
33950 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 70 6f  with an entry po
33960 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 61 6c  int X that is al
33970 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20  ready.** on the 
33980 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 74 69  list of automati
33990 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 73 20  c extensions is 
339a0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
339b0 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e  . ^No entry poin
339c0 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c  t.** will be cal
339d0 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  led more than on
339e0 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ce for each data
339f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33a00 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a  that is opened..
33a10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33a20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
33a30 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
33a40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33a50 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
33a60 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69  void (*xEntryPoi
33a70 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a  nt)(void));../*.
33a80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
33a90 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
33aa0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
33ab0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
33ac0 66 61 63 65 20 64 69 73 61 62 6c 65 73 20 61 6c  face disables al
33ad0 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  l automatic exte
33ae0 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c  nsions previousl
33af0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33b00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61  using [sqlite3_a
33b10 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
33b20 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
33b30 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
33b40 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f  ension(void);../
33b50 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
33b60 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
33b70 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
33b80 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  m is currently c
33b90 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
33ba0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
33bb0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
33bc0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
33bd0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
33be0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
33bf0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
33c00 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
33c10 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
33c20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
33c30 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
33c40 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
33c50 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
33c60 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
33c70 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
33c80 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
33c90 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
33ca0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
33cb0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
33cc0 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65  * Structures use
33cd0 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
33ce0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
33cf0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
33d00 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
33d10 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79  sqlite3_vtab;.ty
33d20 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
33d30 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
33d40 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
33d50 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  fo;.typedef stru
33d60 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
33d70 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76  cursor sqlite3_v
33d80 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65  tab_cursor;.type
33d90 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
33da0 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65  e3_module sqlite
33db0 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a  3_module;../*.**
33dc0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
33dd0 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a  al Table Object.
33de0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
33df0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72  ite3_module {vir
33e00 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
33e10 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74  e}.**.** This st
33e20 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d  ructure, sometim
33e30 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76  es called a a "v
33e40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33e50 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65  ule", .** define
33e60 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  s the implementa
33e70 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75  tion of a [virtu
33e80 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a  al tables].  .**
33e90 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
33ea0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20  consists mostly 
33eb0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
33ec0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
33ed0 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c   ^A virtual tabl
33ee0 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61  e module is crea
33ef0 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69  ted by filling i
33f00 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  n a persistent.*
33f10 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
33f20 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  is structure and
33f30 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74   passing a point
33f40 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61  er to that insta
33f50 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nce.** to [sqlit
33f60 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
33f70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33f80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
33f90 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67  ()]..** ^The reg
33fa0 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
33fb0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
33fc0 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
33fd0 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
33fe0 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
33ff0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34000 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
34010 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
34020 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
34030 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
34040 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
34050 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
34060 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
34070 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
34080 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
34090 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
340a0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
340b0 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
340c0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
340d0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
340e0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
340f0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
34100 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
34110 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
34120 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
34130 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
34140 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
34150 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
34160 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
34170 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
34180 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
34190 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
341a0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
341b0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
341c0 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
341d0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
341e0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
341f0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
34200 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
34210 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
34220 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
34230 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
34240 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
34250 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
34260 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
34270 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
34280 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
34290 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
342a0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
342b0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
342c0 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
342d0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
342e0 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
342f0 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
34300 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
34310 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
34320 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
34330 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
34340 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
34350 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
34360 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34370 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
34380 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
34390 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
343a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
343b0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
343c0 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
343d0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
343e0 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
343f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
34400 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
34410 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
34420 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
34430 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
34440 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
34450 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
34460 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
34470 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
34480 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
34490 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
344a0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
344b0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
344c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
344d0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
344e0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
344f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
34500 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
34510 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34520 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
34530 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
34540 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
34550 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
34560 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
34570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34580 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
34590 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
345a0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
345b0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
345c0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
345d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
345e0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
345f0 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
34600 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  tion.** KEYWORDS
34610 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  : sqlite3_index_
34620 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  info.**.** The s
34630 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
34640 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
34650 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
34660 73 20 69 73 20 75 73 65 64 20 61 73 20 70 61 72  s is used as par
34670 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  t.** of the [vir
34680 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65  tual table] inte
34690 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73  rface to.** pass
346a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
346b0 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
346c0 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
346d0 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
346e0 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
346f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
34700 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
34710 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
34720 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
34730 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
34740 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
34750 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
34760 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
34770 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
34780 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
34790 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lds..**.** ^(The
347a0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
347b0 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
347c0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
347d0 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  aints of the for
347e0 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  m:.**.** <blockq
347f0 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  uote>column OP e
34800 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  xpr</blockquote>
34810 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
34820 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
34830 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
34840 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74  =.)^  ^(The part
34850 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
34860 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  is.** stored in 
34870 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
34880 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
34890 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44  e.** [SQLITE_IND
348a0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
348b0 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f   | SQLITE_INDEX_
348c0 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c 75  CONSTRAINT_ valu
348d0 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20  es].)^.** ^(The 
348e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
348f0 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e  umn is stored in
34900 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
34910 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28  ].iColumn.)^  ^(
34920 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
34930 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
34940 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
34950 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
34960 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
34970 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
34980 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
34990 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
349a0 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
349b0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  t.)^.**.** ^The 
349c0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
349d0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
349e0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
349f0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
34a00 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
34a10 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
34a20 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
34a30 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
34a40 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
34a50 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
34a60 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
34a70 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
34a80 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
34a90 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e  le..** ^The aCon
34aa0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
34ab0 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45  only reports WHE
34ac0 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
34ad0 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65  that are.** rele
34ae0 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74  vant to the part
34af0 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74  icular virtual t
34b00 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69  able being queri
34b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72  ed..**.** ^Infor
34b20 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
34b30 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
34b40 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
34b50 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61  rderBy[]..** ^Ea
34b60 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
34b70 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
34b80 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
34b90 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
34ba0 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
34bb0 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
34bc0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
34bd0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
34be0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
34bf0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
34c00 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
34c10 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49  lter.  ^If argvI
34c20 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
34c30 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
34c40 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
34c50 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
34c60 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
34c70 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
34c80 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
34c90 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
34ca0 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61  .  ^(If aConstra
34cb0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
34cc0 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
34cd0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
34ce0 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
34cf0 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
34d00 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
34d10 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
34d20 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
34d30 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a  by SQLite.)^.**.
34d40 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61  ** ^The idxNum a
34d50 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
34d60 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
34d70 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
34d80 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
34d90 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69  ethod..** ^[sqli
34da0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75  te3_free()] is u
34db0 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50  sed to free idxP
34dc0 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  tr if and only i
34dd0 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
34de0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
34df0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42  *.** ^The orderB
34e00 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20  yConsumed means 
34e10 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d  that output from
34e20 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78   [xFilter]/[xNex
34e30 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  t] will occur in
34e40 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
34e50 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
34e60 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
34e70 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
34e80 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
34e90 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
34ea0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
34eb0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
34ec0 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
34ed0 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
34ee0 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
34ef0 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
34f00 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
34f10 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
34f20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
34f30 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
34f40 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
34f50 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
34f60 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
34f70 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
34f80 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
34f90 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
34fa0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
34fb0 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
34fc0 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e  * Inputs */.  in
34fd0 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
34fe0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
34ff0 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
35000 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
35010 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
35020 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
35030 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
35040 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
35050 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
35060 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
35070 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
35080 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
35090 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
350a0 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
350b0 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
350c0 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
350d0 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
350e0 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
350f0 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
35100 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
35110 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
35120 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
35130 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
35140 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
35150 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
35160 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
35170 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
35180 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
35190 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65  s */.  int nOrde
351a0 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
351b0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
351c0 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
351d0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
351e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
351f0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
35200 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
35210 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
35220 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
35230 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
35240 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
35250 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
35260 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
35270 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64  SC. */.  } *aOrd
35280 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
35290 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
352a0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
352b0 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
352c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
352d0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
352e0 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
352f0 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
35300 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
35310 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
35320 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
35330 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
35340 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
35350 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
35360 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
35370 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
35380 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
35390 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69  ntUsage;.  int i
353a0 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
353b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
353c0 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
353d0 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20   the index */.  
353e0 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20  char *idxStr;   
353f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
35400 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f  ring, possibly o
35410 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
35420 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20  ite3_malloc */. 
35430 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49   int needToFreeI
35440 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46  dxStr;      /* F
35450 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67  ree idxStr using
35460 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
35470 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74  if true */.  int
35480 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
35490 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
354a0 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72  if output is alr
354b0 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a  eady ordered */.
354c0 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74    double estimat
354d0 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20  edCost;      /* 
354e0 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f  Estimated cost o
354f0 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64  f using this ind
35500 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ex */.};../*.** 
35510 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
35520 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72 61 69  l Table Constrai
35530 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f 64 65  nt Operator Code
35540 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61  s.**.** These ma
35550 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74 68 65  cros defined the
35560 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
35570 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  for the.** [sqli
35580 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e  te3_index_info].
35590 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
355a0 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20 76 61   field.  Each va
355b0 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73 0a 2a  lue represents.*
355c0 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20 74 68  * an operator th
355d0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
355e0 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72 6d 20  constraint term 
355f0 69 6e 20 74 68 65 20 77 48 45 52 45 20 63 6c 61  in the wHERE cla
35600 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72  use of.** a quer
35610 79 20 74 68 61 74 20 75 73 65 73 20 61 20 5b 76  y that uses a [v
35620 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
35630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35640 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
35650 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
35660 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
35670 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
35680 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
35690 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
356a0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
356b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
356c0 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
356d0 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
356e0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
356f0 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
35700 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
35710 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
35720 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
35730 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
35740 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
35750 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
35760 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
35770 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
35780 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
35790 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
357a0 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
357b0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
357c0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
357d0 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
357e0 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
357f0 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
35800 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65  he module and be
35810 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
35820 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
35830 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
35840 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
35850 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
35860 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
35870 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
35880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
35890 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
358a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
358b0 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
358c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
358d0 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
358e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
358f0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
35900 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
35910 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
35920 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
35930 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
35940 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
35950 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
35960 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
35970 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
35980 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
35990 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
359a0 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
359b0 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
359c0 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
359d0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
359e0 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
359f0 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
35a00 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
35a10 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
35a20 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
35a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35a40 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
35a50 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
35a60 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
35a70 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
35a80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
35a90 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
35aa0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
35ab0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
35ac0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
35ad0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
35ae0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
35af0 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
35b00 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
35b10 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
35b20 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
35b30 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
35b40 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69 6e 76 6f   also.** be invo
35b50 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
35b60 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
35b70 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 66 61  e_module_v2() fa
35b80 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ils..** ^The sql
35b90 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
35ba0 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  le().** interfac
35bb0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
35bc0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
35bd0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69  e_module_v2() wi
35be0 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73  th a NULL.** des
35bf0 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  tructor..*/.int 
35c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
35c10 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
35c20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35c30 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
35c40 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
35c50 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
35c60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
35c70 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
35c80 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
35c90 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
35ca0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
35cb0 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
35cc0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
35cd0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
35ce0 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
35cf0 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
35d00 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
35d10 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  nect */.);.int s
35d20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
35d30 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
35d40 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
35d50 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
35d60 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
35d70 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
35d80 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
35d90 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
35da0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
35db0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
35dc0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
35dd0 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
35de0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
35df0 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
35e00 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
35e10 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
35e20 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
35e30 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
35e40 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35e50 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
35e60 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
35e70 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
35e80 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
35e90 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
35ea0 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
35eb0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
35ec0 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  tab.**.** Every 
35ed0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
35ee0 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
35ef0 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
35f00 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73  class.** of this
35f10 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72   object to descr
35f20 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72  ibe a particular
35f30 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20   instance.** of 
35f40 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
35f50 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c  le].  Each subcl
35f60 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
35f70 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
35f80 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
35f90 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
35fa0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
35fb0 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
35fc0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
35fd0 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
35fe0 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
35ff0 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
36000 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
36010 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
36020 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65  * ^Virtual table
36030 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
36040 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
36050 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
36060 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
36070 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36080 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
36090 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
360a0 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
360b0 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
360c0 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
360d0 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
360e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
360f0 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
36100 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
36110 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
36120 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68  rMsg.  ^After th
36130 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
36140 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
36150 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
36160 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
36170 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
36180 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
36190 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
361a0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
361b0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
361c0 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
361d0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
361e0 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
361f0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36200 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
36210 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
36220 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
36230 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
36240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36250 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
36260 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
36270 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
36280 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
36290 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
362a0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
362b0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
362c0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
362d0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
362e0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
362f0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
36300 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
36310 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
36320 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
36330 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
36340 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
36350 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  or {virtual tabl
36360 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20  e cursor}.**.** 
36370 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
36380 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
36390 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
363a0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
363b0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
363c0 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
363d0 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
363e0 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
363f0 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  e.** [virtual ta
36400 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65  ble] and are use
36410 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72  d.** to loop thr
36420 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c  ough the virtual
36430 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73   table.  Cursors
36440 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
36450 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
36460 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20  e3_module.xOpen 
36470 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  | xOpen] method 
36480 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  of the module an
36490 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a  d are destroyed.
364a0 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ** by the [sqlit
364b0 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65  e3_module.xClose
364c0 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f   | xClose] metho
364d0 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  d.  Cursors are 
364e0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  used.** by the [
364f0 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74  xFilter], [xNext
36500 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c  ], [xEof], [xCol
36510 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69  umn], and [xRowi
36520 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  d] methods.** of
36530 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
36540 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
36550 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
36560 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
36570 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
36580 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
36590 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
365a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
365b0 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
365c0 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
365d0 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
365e0 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
365f0 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
36600 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
36610 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
36620 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
36630 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
36640 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
36650 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
36660 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
36670 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
36680 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
36690 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
366a0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
366b0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
366c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
366d0 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
366e0 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
366f0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  able.**.** ^The 
36700 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
36710 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
36720 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
36730 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
36740 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
36750 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
36760 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
36770 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
36780 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
36790 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
367a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
367b0 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
367c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
367d0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
367e0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
367f0 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *zSQL);../*.** C
36800 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
36810 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
36820 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
36830 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c  .**.** ^(Virtual
36840 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
36850 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
36860 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36870 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
36880 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64  using the [xFind
36890 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64  Function] method
368a0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
368b0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
368c0 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20   .** But global 
368d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
368e0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
368f0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
36900 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
36910 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ded.)^.**.** ^(T
36920 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
36930 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
36940 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
36950 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
36960 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
36970 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
36980 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
36990 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
369a0 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
369b0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
369c0 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
369d0 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
369e0 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d  .)^  ^The implem
369f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
36a00 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
36a10 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e  always causes an
36a20 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65   exception to be
36a30 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20   thrown.  So.** 
36a40 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
36a50 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72   is not good for
36a60 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73   anything by its
36a70 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a  elf.  Its only.*
36a80 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20  * purpose is to 
36a90 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72  be a placeholder
36aa0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
36ab0 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
36ac0 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61  .** by a [virtua
36ad0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74  l table]..*/.int
36ae0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
36af0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
36b00 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
36b10 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
36b20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
36b30 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
36b40 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
36b50 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
36b60 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
36b70 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
36b80 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
36b90 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
36ba0 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
36bb0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
36bc0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
36bd0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
36be0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
36bf0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
36c00 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
36c10 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
36c20 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
36c30 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
36c40 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
36c50 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
36c60 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
36c70 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
36c80 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
36c90 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
36ca0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
36cb0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
36cc0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
36cd0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
36ce0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
36cf0 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
36d00 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
36d10 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
36d20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
36d30 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
36d40 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
36d50 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
36d60 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
36d70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
36d80 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
36d90 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
36da0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
36db0 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
36dc0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
36dd0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
36de0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
36df0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
36e00 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
36e10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
36e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
36e30 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
36e40 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
36e50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
36e60 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
36e70 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
36e80 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
36e90 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
36ea0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
36eb0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
36ec0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
36ed0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
36ee0 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
36ef0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
36f00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
36f10 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
36f20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
36f30 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
36f40 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
36f50 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
36f60 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
36f70 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
36f80 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
36f90 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
36fa0 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
36fb0 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
36fc0 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
36fd0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
36fe0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
36ff0 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
37000 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
37010 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
37020 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
37030 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
37040 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
37050 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
37060 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  e>)^.**.** ^If t
37070 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37080 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
37090 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
370a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
370b0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
370c0 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20  cess. ^If it is 
370d0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
370e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
370f0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74  d access..** ^It
37100 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
37110 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
37120 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
37130 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72  f an index or pr
37140 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f  imary .** key fo
37150 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b  r writing. ^If [
37160 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
37170 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61  traints] are ena
37180 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20  bled, it is .** 
37190 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
371a0 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
371b0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
371c0 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20  [child key] for 
371d0 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  writing..**.** ^
371e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
371f0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
37200 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
37210 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
37220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
37230 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
37240 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
37250 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
37260 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72  ** appears after
37270 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
37280 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
37290 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
372a0 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
372b0 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20  * ^For the main 
372c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
372d0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
372e0 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e   is "main"..** ^
372f0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
37300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
37310 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
37320 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
37330 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
37340 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
37350 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
37360 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
37370 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
37380 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
37390 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
373a0 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20  ned and *ppBlob 
373b0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20  is set.** to be 
373c0 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29  a null pointer.)
373d0 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  ^.** ^This funct
373e0 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
373f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37400 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
37410 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
37420 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
37430 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
37440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
37450 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
37460 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
37470 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
37480 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
37490 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
374a0 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
374b0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
374c0 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
374d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
374e0 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
374f0 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
37500 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
37510 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
37520 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
37530 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68   ^(If the row th
37540 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
37550 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
37560 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
37570 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
37580 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
37590 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
375a0 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
375b0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
375c0 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
375d0 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
375e0 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
375f0 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
37600 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
37610 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
37620 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
37630 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
37640 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e   open on.)^.** ^
37650 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
37660 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
37670 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
37680 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
37690 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
376a0 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
376b0 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
376c0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
376d0 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20  ]..** ^(Changes 
376e0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
376f0 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
37700 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
37710 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64  re not.** rolled
37720 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70   back by the exp
37730 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42  iration of the B
37740 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67  LOB.  Such chang
37750 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  es will eventual
37760 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20  ly.** commit if 
37770 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
37780 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
37790 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  pletion.)^.**.**
377a0 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74   ^Use the [sqlit
377b0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
377c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65   interface to de
377d0 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
377e0 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65   of.** the opene
377f0 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69  d blob.  ^The si
37800 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79  ze of a blob may
37810 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20   not be changed 
37820 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  by this.** inter
37830 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b  face.  Use the [
37840 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d  UPDATE] SQL comm
37850 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  and to change th
37860 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62  e size of a.** b
37870 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lob..**.** ^The 
37880 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
37890 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73  roblob()] and [s
378a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
378b0 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66  roblob()] interf
378c0 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20  aces.** and the 
378d0 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c  built-in [zerobl
378e0 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ob] SQL function
378f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66   can be used, if
37900 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20   desired,.** to 
37910 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c  create an empty,
37920 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f   zero-filled blo
37930 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65  b in which to re
37940 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e  ad or write usin
37950 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  g.** this interf
37960 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  ace..**.** To av
37970 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c  oid a resource l
37980 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20  eak, every open 
37990 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68  [BLOB handle] sh
379a0 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a  ould eventually.
379b0 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ** be released b
379c0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
379d0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
379e0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
379f0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20  e3_blob_open(.  
37a00 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
37a10 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63  t char *zDb,.  c
37a20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
37a30 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e,.  const char 
37a40 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69  *zColumn,.  sqli
37a50 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a  te3_int64 iRow,.
37a60 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73    int flags,.  s
37a70 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70  qlite3_blob **pp
37a80 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Blob.);../*.** C
37a90 41 50 49 33 52 45 46 3a 20 4d 6f 76 65 20 61 20  API3REF: Move a 
37aa0 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74 6f 20 61  BLOB Handle to a
37ab0 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e   New Row.**.** ^
37ac0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
37ad0 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 61 6e   used to move an
37ae0 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 68   existing blob h
37af0 61 6e 64 6c 65 20 73 6f 20 74 68 61 74 20 69 74  andle so that it
37b00 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
37b10 64 69 66 66 65 72 65 6e 74 20 72 6f 77 20 6f 66  different row of
37b20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37b30 73 65 20 74 61 62 6c 65 2e 20 5e 54 68 65 20 6e  se table. ^The n
37b40 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e 74 69  ew row is identi
37b50 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 72  fied.** by the r
37b60 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73 73 65  owid value passe
37b70 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
37b80 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79 20 74  argument. Only t
37b90 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a  he row can be.**
37ba0 20 63 68 61 6e 67 65 64 2e 20 5e 54 68 65 20 64   changed. ^The d
37bb0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
37bc0 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68 69  nd column on whi
37bd0 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61 6e 64  ch the blob hand
37be0 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20 72 65  le is open.** re
37bf0 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e 20 4d  main the same. M
37c00 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74 69 6e  oving an existin
37c10 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 74 6f  g blob handle to
37c20 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e 20 62   a new row can b
37c30 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e  e.** faster than
37c40 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65 78 69   closing the exi
37c50 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61 6e 64  sting handle and
37c60 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77 20 6f   opening a new o
37c70 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ne..**.** ^(The 
37c80 6e 65 77 20 72 6f 77 20 6d 75 73 74 20 6d 65 65  new row must mee
37c90 74 20 74 68 65 20 73 61 6d 65 20 63 72 69 74 65  t the same crite
37ca0 72 69 61 20 61 73 20 66 6f 72 20 5b 73 71 6c 69  ria as for [sqli
37cb0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
37cc0 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74 20 65 78   -.** it must ex
37cd0 69 73 74 20 61 6e 64 20 74 68 65 72 65 20 6d 75  ist and there mu
37ce0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 62  st be either a b
37cf0 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75  lob or text valu
37d00 65 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 74  e stored in.** t
37d10 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 63 6f 6c  he nominated col
37d20 75 6d 6e 2e 29 5e 20 5e 49 66 20 74 68 65 20 6e  umn.)^ ^If the n
37d30 65 77 20 72 6f 77 20 69 73 20 6e 6f 74 20 70 72  ew row is not pr
37d40 65 73 65 6e 74 20 69 6e 20 74 68 65 20 74 61 62  esent in the tab
37d50 6c 65 2c 20 6f 72 20 69 66 0a 2a 2a 20 69 74 20  le, or if.** it 
37d60 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 74 61 69 6e  does not contain
37d70 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 74 20   a blob or text 
37d80 76 61 6c 75 65 2c 20 6f 72 20 69 66 20 61 6e 6f  value, or if ano
37d90 74 68 65 72 20 65 72 72 6f 72 20 6f 63 63 75 72  ther error occur
37da0 73 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  s, an.** SQLite 
37db0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
37dc0 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 62  turned and the b
37dd0 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20 63 6f  lob handle is co
37de0 6e 73 69 64 65 72 65 64 20 61 62 6f 72 74 65 64  nsidered aborted
37df0 2e 0a 2a 2a 20 5e 41 6c 6c 20 73 75 62 73 65 71  ..** ^All subseq
37e00 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
37e10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
37e20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ()], [sqlite3_bl
37e30 6f 62 5f 77 72 69 74 65 28 29 5d 20 6f 72 0a 2a  ob_write()] or.*
37e40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
37e50 72 65 6f 70 65 6e 28 29 5d 20 6f 6e 20 61 6e 20  reopen()] on an 
37e60 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61 6e  aborted blob han
37e70 64 6c 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  dle immediately 
37e80 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
37e90 5f 41 42 4f 52 54 2e 20 5e 43 61 6c 6c 69 6e 67  _ABORT. ^Calling
37ea0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
37eb0 79 74 65 73 28 29 5d 20 6f 6e 20 61 6e 20 61 62  ytes()] on an ab
37ec0 6f 72 74 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c  orted blob handl
37ed0 65 0a 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75  e.** always retu
37ee0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
37ef0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73  ^This function s
37f00 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ets the database
37f10 20 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f   handle error co
37f20 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 2e 0a  de and message..
37f30 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
37f40 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
37f50 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 73  e3_blob_reopen(s
37f60 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 73  qlite3_blob *, s
37f70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
37f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37f90 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e  Close A BLOB Han
37fa0 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65  dle.**.** ^Close
37fb0 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  s an open [BLOB 
37fc0 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  handle]..**.** ^
37fd0 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73  Closing a BLOB s
37fe0 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63  hall cause the c
37ff0 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
38000 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20  on to commit.** 
38010 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
38020 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20  other BLOBs, no 
38030 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64  pending prepared
38040 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
38050 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
38060 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69   connection is i
38070 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  n [autocommit mo
38080 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  de]..** ^If any 
38090 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
380a0 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
380b0 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
380c0 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
380d0 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
380e0 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
380f0 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e  ill fit..**.** ^
38100 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f  (Closing the BLO
38110 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74  B often forces t
38120 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75  he changes.** ou
38130 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f  t to disk and so
38140 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f   if any I/O erro
38150 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77  rs occur, they w
38160 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72  ill likely occur
38170 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20  .** at the time 
38180 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  when the BLOB is
38190 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72   closed.  Any er
381a0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
381b0 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e  during.** closin
381c0 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61  g are reported a
381d0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  s a non-zero ret
381e0 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a  urn value.)^.**.
381f0 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73  ** ^(The BLOB is
38200 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
38210 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
38220 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
38230 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
38240 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
38250 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
38260 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  d.)^.**.** ^Call
38270 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
38280 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69   with a null poi
38290 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f  nter (such as wo
382a0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a  uld be returned.
382b0 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63  ** by a failed c
382c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
382d0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73  blob_open()]) is
382e0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
382f0 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
38300 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c  3_blob_close(sql
38310 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
38320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38330 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
38340 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  f An Open BLOB.*
38350 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68  *.** ^Returns th
38360 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
38370 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65  of the BLOB acce
38380 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a  ssible via the .
38390 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ** successfully 
383a0 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e  opened [BLOB han
383b0 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79  dle] in its only
383c0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
383d0 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  .** incremental 
383e0 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65  blob I/O routine
383f0 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20  s can only read 
38400 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65  or overwriting e
38410 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20  xisting.** blob 
38420 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61  content; they ca
38430 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
38440 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a  size of a blob..
38450 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
38460 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
38470 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
38480 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
38490 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
384a0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
384b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
384c0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
384d0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
384e0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
384f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
38500 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
38510 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
38520 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
38530 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
38540 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
38550 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
38560 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
38570 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
38580 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71  e3_blob_bytes(sq
38590 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
385a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
385b0 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41  Read Data From A
385c0 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
385d0 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  lly.**.** ^(This
385e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
385f0 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
38600 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  rom an open [BLO
38610 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61  B handle] into a
38620 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c  .** caller-suppl
38630 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79  ied buffer. N by
38640 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
38650 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66  copied into buff
38660 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  er Z.** from the
38670 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72   open BLOB, star
38680 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
38690 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  Offset.)^.**.** 
386a0 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73  ^If offset iOffs
386b0 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
386c0 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
386d0 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
386e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
386f0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
38700 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
38710 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69  ead.  ^If N or i
38720 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73  Offset is.** les
38730 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51  s than zero, [SQ
38740 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
38750 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
38760 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20  ata is read..** 
38770 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65  ^The size of the
38780 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65   blob (and hence
38790 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
387a0 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
387b0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
387c0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
387d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
387e0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
387f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65  ..**.** ^An atte
38800 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d  mpt to read from
38810 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
38820 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
38830 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
38840 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
38850 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  _ABORT]..**.** ^
38860 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c  (On success, sql
38870 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
38880 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
38890 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  OK..** Otherwise
388a0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
388b0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
388c0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
388d0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
388e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
388f0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
38900 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
38910 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has b