/ Hex Artifact Content
Login

Artifact 0cf61c41c48e1e6b863ff8cf9ecd69620932330e:


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 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
41d0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
41e0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
41f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4200: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4210: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4220: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4230: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4250: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4260: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4280: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4290: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42a0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
42c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
42d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
42e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
42f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4310: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4320: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4330: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4360: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4370: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4380: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4390: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
43c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
43f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4400: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4410: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4420: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4430: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4440: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4460: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4470: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4480: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4490: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
44c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
44f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4500: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4510: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4520: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4530: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4540: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4550: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4560: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4570: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4580: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4590: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
45c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
45d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
45e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
45f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4620: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4630: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4640: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4650: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4660: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4670: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4680: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4690: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46a0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46b0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
46c0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
46d0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
46e0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
46f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4700: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4710: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4720: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4730: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4740: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4750: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4760: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4770: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4780: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4790: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47a0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47b0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
47c0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
47d0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
47e0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
47f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4800: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4810: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4820: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4830: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4840: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4850: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4860: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4870: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4880: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4890: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48a0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48b0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
48c0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
48d0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
48e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
48f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4900: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4910: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4930: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4940: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4950: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4960: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4970: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4980: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4990: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49a0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49b0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
49c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
49d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49e0: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
49f0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a00: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a10: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a20: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a30: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a40: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a50: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4a60: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4a70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4a80: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4a90: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4aa0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4ab0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4ac0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4af0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b00: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4ce0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d20: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4d60: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4da0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4de0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e20: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4e60: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ea0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f20: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5020: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
5060: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5070: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5080: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5090: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50a0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50b0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
50c0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
50d0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
50e0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
50f0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5100: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
5110: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5120: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5130: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5140: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5150: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5160: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5170: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5180: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5190: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
51a0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
51b0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
51c0: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
51d0: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
51e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
51f0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5200: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5210: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5220: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5230: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5240: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5250: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5260: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5270: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5280: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5290: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
52a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
52b0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
52c0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
52d0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
52e0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
52f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5300: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5310: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5320: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5340: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5350: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5360: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5370: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5380: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5390: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
53a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
53c0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
53d0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
53e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5400: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5410: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
5420: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
5440: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
5450: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
5460: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5470: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5480: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5490: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
54a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
54c0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
54d0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
54e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5500: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5510: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
5520: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5530: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5540: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5550: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
5560: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5570: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5580: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5590: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
55a0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
55b0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
55c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
55d0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
55e0: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
55f0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5600: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5610: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
5620: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
5630: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
5640: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5650: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5660: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
5670: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5680: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5690: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
56a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
56b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
56d0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
56e0: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
56f0: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5710: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
5720: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
5730: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
5740: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
5750: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
5760: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
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 6f 62 6a 65  methods].** obje
5790: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
57a0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
57b0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
57c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
57d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
57e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
57f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5800: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5810: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5820: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5840: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5850: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5860: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
5870: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5880: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5890: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
58a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
58d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
58e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
58f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5900: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5910: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5920: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5930: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5940: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5950: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5960: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5970: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5980: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5990: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
59a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
59b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
59c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
59d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
59e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
59f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5a00: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5a10: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a20: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5a30: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5a40: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5a50: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5a60: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5a70: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a80: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ac0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ae0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5af0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5b10: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b30: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5b60: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ba0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5bb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5bd0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5be0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5bf0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5c40: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c60: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5c70: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c90: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5ca0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5cb0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5cc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5cd0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5ce0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d00: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5d10: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5d20: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5d30: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5d40: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5d50: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5d60: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5d70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d80: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d90: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5da0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5db0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5dc0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5dd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5de0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5e10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5e20: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5e30: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5e40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5e50: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5e70: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5ea0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5eb0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5ec0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5ed0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5ee0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5ef0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5f00: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5f10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5f20: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5f30: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5f40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5f50: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5f60: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5f70: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f80: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f90: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5fa0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5fb0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5fc0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5fd0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5fe0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5ff0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6000: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6010: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6020: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6030: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6040: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6050: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6060: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6070: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6080: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6090: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
60a0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
60b0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
60c0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
60d0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
60e0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
60f0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6100: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6110: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6120: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6130: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6140: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6150: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6160: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6180: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6190: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
61a0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
61b0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
61c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
61d0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
61e0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
61f0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6200: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6210: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6220: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6230: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6240: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
6250: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
6260: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
6270: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6280: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6290: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
62a0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
62b0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
62c0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
62d0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
62e0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
62f0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6300: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6310: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
6320: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
6330: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6340: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
6350: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
6360: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
6370: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6380: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6390: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
63a0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
63b0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
63c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
63d0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
63e0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
63f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6420: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
6430: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
6440: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6450: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
6460: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
6470: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6480: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6490: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
64a0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
64b0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
64c0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
64d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
64e0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
64f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6500: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6510: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
6520: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
6530: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
6540: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
6550: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6560: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6570: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6580: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6590: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
65a0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
65b0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
65c0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
65d0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
65e0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
65f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6600: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6610: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6620: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
6630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6640: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
6650: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6660: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6670: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6680: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6690: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
66a0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
66b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
66c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
66d0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
66e0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
66f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6700: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6710: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
6720: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
6730: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
6740: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
6750: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
6760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
6770: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6780: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6790: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
67a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
67b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
67c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
67d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
67e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
67f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6810: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
6820: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
6830: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
6840: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
6850: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
6860: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
6870: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6880: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6890: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
68a0: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
68b0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
68c0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
68d0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
68e0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
68f0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6900: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6910: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
6920: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
6930: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6940: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
6950: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
6960: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6970: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6980: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6990: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
69a0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
69b0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
69c0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
69d0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
69e0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
69f0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6a00: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6a10: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
6a20: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
6a30: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6a40: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6a50: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6a60: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6a70: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a80: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a90: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6aa0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ab0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6ac0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6ad0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6ae0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6af0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6b00: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6b10: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6b20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6b30: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6b50: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6b60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6b70: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b80: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b90: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6ba0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6bb0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6bc0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6bd0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6be0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6bf0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6c00: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6c10: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6c20: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6c30: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6c40: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6c50: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6c60: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6c70: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c80: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c90: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6ca0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6cb0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6cc0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6cd0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6ce0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6cf0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6d00: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6d10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6d20: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6d30: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6d40: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6d50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6d60: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6d70: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d80: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d90: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6da0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6db0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6dc0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6dd0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6de0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6df0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6e00: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6e10: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6e20: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6e30: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6e40: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6e50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6e60: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6e70: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e80: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e90: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6ea0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6eb0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6ec0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6ed0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6ee0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6ef0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6f00: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6f10: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6f20: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6f30: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6f40: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6f50: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6f60: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6f70: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f80: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f90: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6fa0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6fb0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6fc0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6fd0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6fe0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6ff0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7000: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7010: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7020: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7030: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7040: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7050: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7060: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7070: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7080: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7090: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
70a0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
70b0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
70c0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
70d0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
70e0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
70f0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7100: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7110: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7120: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7130: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7140: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7150: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7160: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7170: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7180: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7190: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
71a0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
71b0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
71c0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
71d0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
71e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
71f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7200: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7210: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7220: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7260: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7270: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7280: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7290: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
72a0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
72b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
72c0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
72d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
72e0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
72f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7300: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7310: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7320: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7330: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7340: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7350: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7360: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7370: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7380: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7390: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
73a0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
73b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73c0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
73d0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
73e0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
73f0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7400: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7410: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7420: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7430: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7440: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7450: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7460: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7470: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7480: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7490: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
74a0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
74b0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
74c0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
74d0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
74e0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
74f0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7500: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7510: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7520: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7530: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7540: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7550: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7560: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7570: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7580: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7590: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
75a0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
75b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
75c0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
75d0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
75e0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
75f0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7600: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7610: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7620: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7630: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7640: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7650: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7660: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7670: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7680: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7690: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
76a0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
76b0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
76c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
76d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
76e0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
76f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7700: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7710: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7720: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7730: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
7740: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
7750: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7760: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7770: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7780: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7790: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
77a0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
77b0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
77c0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
77d0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
77e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
77f0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7800: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7810: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
7820: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
7830: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7840: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7850: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
7860: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
7870: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7880: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
78a0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
78b0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
78c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
78d0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
78e0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
78f0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7900: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7910: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
7920: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
7930: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7940: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
7950: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
7960: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7970: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7980: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7990: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
79a0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
79b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
79c0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
79d0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
79e0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
79f0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7a00: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7a10: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
7a20: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
7a30: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
7a40: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7a50: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
7a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a70: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a80: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a90: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7aa0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7ab0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7ac0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7ad0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7ae0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7af0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7b00: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7b10: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7b20: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7b30: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7b40: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7b50: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7b60: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7b70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b80: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7ba0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7bb0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7bc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7bd0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7be0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7bf0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7c00: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7c10: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7c20: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7c30: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7c40: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7c50: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7c60: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7c70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c80: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7ca0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7cb0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7cc0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7cd0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7ce0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7cf0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7d00: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7d10: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7d20: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7d30: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7d40: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7d50: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7d60: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7d70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d80: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d90: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7da0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7db0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7dc0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7dd0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7de0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7df0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7e00: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7e10: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7e20: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7e40: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7e50: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7e60: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7e70: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e80: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e90: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7ea0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7eb0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7ec0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7ed0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7ee0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7ef0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7f00: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7f10: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7f20: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7f30: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7f40: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7f50: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7f60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7f70: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f80: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f90: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7fa0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7fb0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7fc0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7fd0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7fe0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7ff0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8000: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8010: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8020: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8030: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8040: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8050: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8060: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8070: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8080: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8090: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
80a0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
80b0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
80c0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
80d0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
80e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
80f0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8100: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8110: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8120: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8130: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8140: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8150: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8160: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8170: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8180: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8190: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
81a0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
81b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
81c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
81d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
81e0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
81f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8200: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8210: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8220: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8230: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8240: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8250: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8260: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8270: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8280: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8290: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
82a0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
82b0: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
82c0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
82d0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
82e0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
82f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8300: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8310: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8320: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8330: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8340: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8350: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8360: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8370: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8380: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8390: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
83a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
83b0: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
83c0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
83d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
83e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
83f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8400: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8410: 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66  re it.  .*/.#def
8420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8430: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
8440: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
8450: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
8460: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
8470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
8480: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8490: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
84a0: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
84b0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
84c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
84d0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
84e0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
84f0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8500: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
8510: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8520: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
8530: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
8540: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8550: 49 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a  ITTED     8.../*
8560: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
8570: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
8580: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
8590: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
85a0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
85b0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
85c0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
85d0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
85e0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
85f0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
8600: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
8610: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
8620: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
8630: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
8640: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
8650: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
8660: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
8670: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
8680: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
8690: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
86a0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
86b0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
86c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
86d0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
86e0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
86f0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
8700: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
8710: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
8720: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
8730: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
8740: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
8750: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
8760: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
8770: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
8780: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
8790: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
87a0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
87b0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
87c0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
87d0: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
87e0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
87f0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
8800: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
8810: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
8820: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8830: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
8840: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
8850: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
8860: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
8870: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
8880: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
8890: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
88a0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
88b0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
88c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
88d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
88e0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
88f0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
8900: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
8910: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
8920: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
8930: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
8940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
8950: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
8960: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
8970: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
8980: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
8990: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
89a0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
89b0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
89c0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
89d0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
89e0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
89f0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
8a00: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
8a10: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
8a20: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
8a30: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
8a40: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
8a50: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
8a60: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
8a70: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
8a80: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
8a90: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
8aa0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
8ab0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
8ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
8ad0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
8ae0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
8af0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
8b00: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
8b10: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
8b20: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8b30: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
8b40: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
8b50: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
8b60: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
8b70: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
8b80: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
8b90: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
8ba0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
8bb0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
8bc0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
8bd0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
8be0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
8bf0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
8c00: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
8c10: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
8c20: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
8c30: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
8c40: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
8c50: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
8c60: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
8c70: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
8c80: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
8c90: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
8ca0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8cb0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
8cc0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
8cd0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
8ce0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
8cf0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  .**.** ^SQLite g
8d00: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
8d10: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8d20: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
8d30: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
8d40: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
8d50: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
8d60: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
8d70: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
8d80: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
8d90: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
8da0: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
8db0: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
8dc0: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
8dd0: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
8de0: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
8df0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
8e00: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
8e10: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65  .** 10 alphanume
8e20: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
8e30: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
8e40: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
8e50: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
8e60: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
8e70: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
8e80: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
8e90: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
8ea0: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
8eb0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
8ec0: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
8ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
8ee0: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
8ef0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
8f00: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
8f10: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
8f20: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
8f30: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
8f40: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
8f50: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8f60: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
8f70: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
8f80: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
8f90: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
8fa0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
8fb0: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
8fc0: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
8fd0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8fe0: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
8ff0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
9000: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
9010: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
9020: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
9030: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9040: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
9050: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
9060: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
9070: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
9080: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
9090: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
90a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
90b0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
90c0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
90d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
90e0: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
90f0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
9100: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
9110: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
9120: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
9130: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
9140: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
9150: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
9160: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
9170: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
9180: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
9190: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
91a0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
91b0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
91c0: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
91d0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
91e0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
91f0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
9200: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
9210: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
9220: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
9230: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
9240: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
9250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
9260: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
9270: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
9280: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
9290: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
92a0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
92b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
92c0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
92d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
92e0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
92f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9300: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
9310: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9320: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
9330: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9340: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
9350: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
9360: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
9370: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
9380: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
9390: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
93a0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
93b0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
93c0: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
93d0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
93e0: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
93f0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
9400: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
9410: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
9420: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
9430: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
9440: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
9450: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
9460: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
9470: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
9480: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
9490: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
94a0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
94b0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
94c0: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
94d0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
94e0: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
94f0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9500: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
9510: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
9520: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
9530: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
9540: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
9550: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
9560: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
9570: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
9580: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
9590: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
95a0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
95b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
95c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
95d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
95e0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
95f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
9600: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
9610: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
9620: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9630: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
9640: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
9650: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
9660: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
9670: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
9680: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
9690: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
96a0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
96b0: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
96c0: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
96d0: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
96e0: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
96f0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
9700: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
9710: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
9720: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
9730: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
9740: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
9750: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
9760: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
9770: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
9780: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
9790: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
97a0: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
97b0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
97c0: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
97d0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
97e0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
97f0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
9800: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
9810: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
9820: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
9830: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
9840: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
9850: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
9860: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
9870: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
9880: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
9890: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
98a0: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
98b0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
98c0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
98d0: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
98e0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
98f0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
9900: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
9910: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
9920: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
9930: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
9940: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
9950: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
9960: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
9970: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
9980: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
9990: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
99a0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
99b0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
99c0: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
99d0: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
99e0: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
99f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
9a00: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
9a10: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
9a20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9a30: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
9a40: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
9a50: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
9a60: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
9a70: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
9a80: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
9a90: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9aa0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
9ab0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
9ac0: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
9ad0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
9ae0: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
9af0: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
9b00: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
9b10: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
9b20: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
9b30: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
9b40: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
9b50: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
9b60: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
9b70: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
9b80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9b90: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
9ba0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
9bb0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9bc0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
9bd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
9be0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
9bf0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
9c00: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
9c10: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
9c20: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
9c30: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
9c40: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
9c50: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
9c60: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
9c70: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
9c80: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
9c90: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
9ca0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
9cb0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9cc0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
9cd0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
9ce0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
9cf0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
9d00: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
9d10: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
9d20: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
9d30: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
9d40: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
9d50: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
9d60: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
9d70: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
9d80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
9d90: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
9da0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
9db0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
9dc0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
9dd0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
9de0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
9df0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
9e00: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
9e10: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
9e20: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
9e30: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
9e40: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9e50: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9e60: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9e70: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9e80: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9e90: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9ea0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9eb0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
9ec0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
9ed0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
9ee0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
9ef0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
9f00: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
9f10: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
9f20: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
9f30: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9f40: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9f50: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9f60: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9f70: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9f80: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9f90: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9fa0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
9fb0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
9fc0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
9fd0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
9fe0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
9ff0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
a000: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
a010: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
a020: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
a030: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
a040: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a050: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
a060: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
a070: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
a080: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
a090: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
a0a0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
a0b0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
a0c0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
a0d0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
a0e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
a0f0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
a100: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
a110: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
a120: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
a130: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
a140: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
a150: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
a160: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
a170: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
a180: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
a190: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
a1a0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
a1b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
a1c0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
a1d0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
a1e0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
a1f0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
a200: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
a210: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
a220: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
a230: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
a240: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
a250: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
a260: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
a270: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
a280: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
a290: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
a2a0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
a2b0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
a2c0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
a2d0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
a2e0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
a2f0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
a300: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
a310: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
a320: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
a330: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
a340: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
a350: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
a360: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
a370: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
a380: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
a390: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
a3a0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
a3b0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
a3c0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
a3d0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
a3e0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
a3f0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
a400: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
a410: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
a420: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
a430: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
a440: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
a450: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
a460: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
a470: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
a480: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
a490: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
a4a0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
a4b0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
a4c0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
a4d0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
a4e0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
a4f0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
a500: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
a510: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
a520: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
a530: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
a540: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
a550: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
a560: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
a570: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
a580: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
a590: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
a5a0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
a5b0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
a5c0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
a5d0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
a5e0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
a5f0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
a600: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
a610: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
a620: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
a630: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
a640: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
a650: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
a660: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
a670: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
a680: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
a690: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
a6a0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
a6b0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
a6c0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
a6d0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
a6e0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
a6f0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a700: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a710: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a720: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a730: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a740: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a750: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a760: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a770: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a780: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a790: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a7a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a7b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a7c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a7d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a7e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a7f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a800: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a810: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a820: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a830: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a840: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a850: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a860: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a870: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a880: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a890: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a8a0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a8b0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a8c0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a8d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a8e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a8f0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a900: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a910: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a920: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a930: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a940: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a950: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a960: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a970: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a980: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a990: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a9a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a9b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a9c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a9d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a9e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a9f0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
aa00: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
aa10: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
aa20: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
aa30: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
aa40: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
aa50: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
aa60: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
aa70: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
aa80: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
aa90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
aaa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
aab0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
aac0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
aad0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
aae0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
aaf0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
ab00: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ab10: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ab20: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ab30: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ab40: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ab50: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ab60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ab70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ab80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ab90: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
aba0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
abb0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
abc0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
abd0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
abe0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
abf0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ac00: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ac10: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ac20: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ac30: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ac40: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ac50: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ac60: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ac70: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ac80: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ac90: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
aca0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
acb0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
acc0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
acd0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ace0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
acf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ad00: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ad10: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ad20: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ad30: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ad40: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
ad50: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
ad60: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
ad70: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
ad80: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
ad90: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
ada0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
adb0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
adc0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
add0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
ade0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
adf0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
ae00: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ae10: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
ae20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
ae30: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
ae40: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
ae50: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
ae60: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ae70: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
ae80: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
ae90: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
aea0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
aeb0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
aec0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
aed0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
aee0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
aef0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
af00: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
af10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
af20: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
af30: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
af40: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
af50: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
af60: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
af70: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
af80: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
af90: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
afa0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
afb0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
afc0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
afd0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
afe0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
aff0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
b000: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
b010: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b020: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
b030: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
b040: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
b050: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
b060: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
b070: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
b080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b090: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
b0a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b0b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
b0c0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
b0d0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
b0e0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
b0f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b100: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
b110: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
b120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b130: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
b140: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
b150: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
b160: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
b170: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
b180: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
b190: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
b1a0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
b1b0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
b1c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b1d0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
b1e0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
b1f0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
b200: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
b210: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
b220: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
b230: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
b240: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b250: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
b260: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b270: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
b280: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b290: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b2a0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
b2b0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b2c0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b2d0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b2e0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
b2f0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
b300: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
b310: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
b320: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
b330: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
b340: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
b350: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
b360: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
b370: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
b380: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
b390: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
b3a0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
b3b0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
b3c0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
b3d0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
b3e0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
b3f0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
b400: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
b410: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
b420: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
b430: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b440: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b450: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b460: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
b470: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
b480: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
b490: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
b4a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
b4b0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
b4c0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
b4d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
b4e0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
b4f0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
b500: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
b510: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
b520: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
b530: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
b540: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
b550: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
b560: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
b570: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
b580: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
b590: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
b5a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b5b0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
b5c0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
b5d0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
b5e0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
b5f0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
b600: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b610: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
b620: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
b630: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
b640: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
b650: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
b660: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
b670: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
b680: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
b690: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
b6a0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
b6b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
b6c0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
b6d0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
b6e0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
b6f0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
b700: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
b710: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
b720: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
b730: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
b740: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
b750: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
b760: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
b770: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
b780: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
b790: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
b7a0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
b7b0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
b7c0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
b7d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
b7e0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
b7f0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
b800: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
b810: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
b820: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
b830: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b840: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
b850: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
b860: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
b870: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
b880: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
b890: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
b8a0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
b8b0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
b8c0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
b8d0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
b8e0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
b8f0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
b900: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b910: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
b920: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
b930: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
b940: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
b950: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
b960: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
b970: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
b980: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
b990: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
b9a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b9b0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
b9c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
b9d0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
b9e0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
b9f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
ba00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
ba10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
ba20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ba30: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
ba40: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
ba50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ba60: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
ba70: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
ba80: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
ba90: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
baa0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
bab0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
bac0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
bad0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
bae0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
baf0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
bb00: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
bb10: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
bb20: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
bb30: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
bb40: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
bb50: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
bb60: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
bb70: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
bb80: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
bb90: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
bba0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
bbb0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
bbc0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
bbd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
bbe0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
bbf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
bc00: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
bc10: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
bc20: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
bc30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
bc40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bc50: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
bc60: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
bc70: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
bc80: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
bc90: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
bca0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
bcb0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
bcc0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
bcd0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
bce0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
bcf0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
bd00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bd10: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
bd20: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
bd30: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
bd40: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
bd50: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
bd60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
bd70: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
bd80: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
bd90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bda0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
bdb0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
bdc0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
bdd0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
bde0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
bdf0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
be00: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
be10: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
be20: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
be30: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
be40: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
be50: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
be60: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
be70: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
be80: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
be90: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
bea0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
beb0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
bec0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
bed0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
bee0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
bef0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
bf00: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
bf10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
bf20: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
bf30: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
bf40: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
bf50: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
bf60: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
bf70: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
bf80: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
bf90: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
bfa0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
bfb0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
bfc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
bfd0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
bfe0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
bff0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
c000: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
c010: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
c020: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
c030: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
c040: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
c050: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
c060: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
c070: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c080: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
c090: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
c0a0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
c0b0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
c0c0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
c0d0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
c0e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
c0f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
c100: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
c110: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
c120: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
c130: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
c140: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
c150: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
c160: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
c170: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
c180: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
c190: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
c1a0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
c1b0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
c1c0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
c1d0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
c1e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
c1f0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
c200: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c210: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
c220: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
c230: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
c240: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
c250: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
c260: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
c270: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
c280: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
c290: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
c2a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c2b0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
c2c0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
c2d0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
c2e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
c2f0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
c300: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c310: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
c320: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c330: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
c340: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
c350: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
c360: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
c370: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
c380: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
c390: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c3a0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
c3b0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
c3c0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
c3d0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
c3e0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
c3f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
c400: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c410: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
c420: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
c430: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
c440: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
c450: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
c460: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
c470: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
c480: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
c490: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
c4a0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
c4b0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
c4c0: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
c4d0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
c4e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
c4f0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
c500: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
c510: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
c520: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
c530: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
c540: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
c550: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
c560: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c570: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c580: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
c590: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
c5a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
c5b0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
c5c0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
c5d0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
c5e0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
c5f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c600: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
c610: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
c620: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
c630: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
c640: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
c650: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
c660: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c670: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
c680: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
c690: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
c6a0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
c6b0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
c6c0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
c6d0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
c6e0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
c6f0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
c700: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
c710: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
c720: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
c730: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
c740: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
c750: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
c760: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
c770: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
c780: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
c790: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
c7a0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
c7b0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
c7c0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
c7d0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
c7e0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
c7f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
c800: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
c810: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
c820: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
c830: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
c840: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
c850: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
c860: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
c870: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
c880: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
c890: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
c8a0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
c8b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
c8c0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
c8d0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
c8e0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
c8f0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
c900: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c910: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
c920: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
c930: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
c940: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
c950: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
c960: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
c970: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
c980: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
c990: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c9a0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
c9b0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
c9c0: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
c9d0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
c9e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
c9f0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
ca00: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
ca10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ca20: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ca30: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
ca40: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
ca50: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
ca60: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ca70: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ca80: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
ca90: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
caa0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
cab0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
cac0: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
cad0: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
cae0: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
caf0: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
cb00: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
cb10: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
cb20: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
cb30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
cb40: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
cb50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
cb60: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
cb70: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
cb80: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
cb90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cba0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
cbb0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
cbc0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
cbd0: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
cbe0: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
cbf0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
cc00: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
cc10: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
cc20: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
cc30: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
cc40: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
cc50: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
cc60: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
cc70: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
cc80: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
cc90: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
cca0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ccb0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ccc0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
ccd0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
cce0: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
ccf0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cd00: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
cd10: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
cd20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
cd30: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
cd40: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
cd50: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
cd60: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
cd70: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
cd80: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
cd90: 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
cda0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
cdb0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
cdc0: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
cdd0: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
cde0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cdf0: 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
ce00: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
ce10: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
ce20: 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
ce30: 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
ce40: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
ce50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
ce60: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
ce70: 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
ce80: 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
ce90: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
cea0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
ceb0: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
cec0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
ced0: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
cee0: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
cef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
cf00: 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
cf10: 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
cf20: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
cf30: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
cf40: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
cf50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cf60: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
cf70: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
cf80: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
cf90: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
cfa0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
cfb0: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
cfc0: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
cfd0: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
cfe0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
cff0: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
d000: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
d010: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
d020: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
d030: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
d040: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
d050: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
d060: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
d070: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
d080: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
d090: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d0a0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
d0b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d0c0: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
d0d0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
d0e0: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
d0f0: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
d100: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
d110: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
d120: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
d130: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
d140: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
d150: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
d160: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
d170: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
d180: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
d190: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d1a0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
d1b0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
d1c0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
d1d0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
d1e0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
d1f0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
d200: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
d210: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
d220: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
d230: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
d240: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
d250: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
d260: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
d270: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
d280: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
d290: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
d2a0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
d2b0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
d2c0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
d2d0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
d2e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
d2f0: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
d300: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
d310: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
d320: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
d330: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
d340: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
d350: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
d360: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
d370: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
d380: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
d390: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
d3a0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
d3b0: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
d3c0: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
d3d0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
d3e0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
d3f0: 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20  alloc and xFree 
d400: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
d410: 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
d420: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
d430: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
d440: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d450: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20  library..** The 
d460: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20  xRealloc method 
d470: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72  must work like r
d480: 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68  ealloc() from th
d490: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
d4a0: 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65  rary.** with the
d4b0: 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20   exception that 
d4c0: 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  if the second ar
d4d0: 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c  gument to xReall
d4e0: 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78  oc is zero,.** x
d4f0: 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20  Realloc must be 
d500: 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73  a no-op - it mus
d510: 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e  t not perform an
d520: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a  y allocation or.
d530: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e  ** deallocation.
d540: 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e    ^SQLite guaran
d550: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
d560: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d570: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
d580: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
d590: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
d5a0: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
d5b0: 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69  dup..** And so i
d5c0: 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52  n cases where xR
d5d0: 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65  oundup always re
d5e0: 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
d5f0: 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61   number,.** xRea
d600: 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d  lloc can perform
d610: 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20   exactly as the 
d620: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
d630: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a   realloc() and.*
d640: 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f  * still be in co
d650: 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68  mpliance with th
d660: 69 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  is specification
d670: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
d680: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
d690: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
d6a0: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
d6b0: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
d6c0: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
d6d0: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
d6e0: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
d6f0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
d700: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
d710: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
d720: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
d730: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
d740: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
d750: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
d760: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
d770: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
d780: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
d790: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
d7a0: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
d7b0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
d7c0: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
d7d0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
d7e0: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
d7f0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
d800: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
d810: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
d820: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
d830: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
d840: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
d850: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
d860: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
d870: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
d880: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
d890: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
d8a0: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
d8b0: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
d8c0: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
d8d0: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
d8e0: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
d8f0: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
d900: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
d910: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
d920: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
d930: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
d940: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
d950: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
d960: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
d970: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
d980: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
d990: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
d9a0: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
d9b0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
d9c0: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
d9d0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
d9e0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
d9f0: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
da00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
da10: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
da20: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
da30: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
da40: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
da50: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
da60: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
da70: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
da80: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
da90: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
daa0: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
dab0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
dac0: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
dad0: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
dae0: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
daf0: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
db00: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
db10: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
db20: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
db30: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
db40: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
db50: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
db60: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
db70: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
db80: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
db90: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
dba0: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
dbb0: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
dbc0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
dbd0: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
dbe0: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
dbf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
dc00: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dc10: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
dc20: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
dc30: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
dc40: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
dc50: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
dc60: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
dc70: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
dc80: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
dc90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dca0: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
dcb0: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
dcc0: 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
dcd0: 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
dce0: 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
dcf0: 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
dd00: 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
dd10: 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
dd20: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
dd30: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
dd40: 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
dd50: 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
dd60: 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
dd70: 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
dd80: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
dd90: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
dda0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
ddb0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
ddc0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
ddd0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
dde0: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
ddf0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
de00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
de10: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
de20: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
de30: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
de40: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
de50: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
de60: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
de70: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
de80: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
de90: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
dea0: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
deb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
dec0: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
ded0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
dee0: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
def0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
df00: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
df10: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
df20: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
df30: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
df40: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
df50: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
df60: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
df70: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
df80: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
df90: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
dfa0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
dfb0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
dfc0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
dfd0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
dfe0: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
dff0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
e000: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
e010: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e020: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
e030: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
e040: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
e050: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
e060: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
e070: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
e080: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
e090: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
e0a0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
e0b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e0c0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
e0d0: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
e0e0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
e0f0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
e100: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
e110: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
e120: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
e130: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
e140: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
e150: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
e160: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
e170: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
e180: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
e190: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
e1a0: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
e1b0: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
e1c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e1d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
e1e0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
e1f0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
e200: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
e210: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
e220: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
e230: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
e240: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
e250: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
e260: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
e270: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
e280: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
e290: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e2a0: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
e2b0: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
e2c0: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
e2d0: 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
e2e0: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
e2f0: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
e300: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
e310: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
e320: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
e330: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
e340: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
e350: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
e360: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
e370: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e380: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e390: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e3a0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e3b0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e3c0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e3d0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e3e0: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
e3f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
e400: 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
e410: 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
e420: 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
e430: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e440: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
e450: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
e460: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
e470: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e480: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
e490: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
e4a0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
e4b0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e4c0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e4d0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e4e0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e4f0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e500: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e510: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e520: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e530: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e540: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e550: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e560: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e570: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e580: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e590: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e5a0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e5b0: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e5c0: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e5d0: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e5e0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e5f0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e600: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e610: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e620: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e630: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e640: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e650: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e660: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e670: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e680: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e690: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e6a0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e6b0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e6c0: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e6d0: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e6e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e6f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
e700: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e710: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
e720: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
e730: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
e740: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
e750: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
e760: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
e770: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e780: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
e790: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e7a0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
e7b0: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
e7c0: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
e7d0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
e7e0: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
e7f0: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e800: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e810: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
e820: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
e830: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
e840: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e850: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
e860: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e870: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
e880: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
e890: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e8a0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
e8b0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
e8c0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
e8d0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
e8e0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
e8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e900: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
e910: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
e920: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
e930: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
e940: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
e950: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e960: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
e970: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
e980: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
e990: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
e9a0: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
e9b0: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
e9c0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
e9d0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
e9e0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
e9f0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
ea00: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
ea10: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
ea20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
ea30: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
ea40: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ea50: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
ea60: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
ea70: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
ea80: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ea90: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
eaa0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
eab0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
eac0: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
ead0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
eae0: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
eaf0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
eb00: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
eb10: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
eb20: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
eb30: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
eb40: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
eb50: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
eb60: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
eb70: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
eb80: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
eb90: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
eba0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ebb0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
ebc0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
ebd0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
ebe0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
ebf0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
ec00: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
ec10: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
ec20: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ec30: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
ec40: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
ec50: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
ec60: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
ec70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ec80: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
ec90: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
eca0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
ecb0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ecc0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
ecd0: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
ece0: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
ecf0: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
ed00: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
ed10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
ed20: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
ed30: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
ed40: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ed50: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
ed60: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
ed70: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ed80: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
ed90: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
eda0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
edb0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
edc0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
edd0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
ede0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
edf0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
ee00: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
ee10: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
ee20: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
ee30: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
ee40: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
ee50: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
ee60: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ee70: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
ee80: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
ee90: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
eea0: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
eeb0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
eec0: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
eed0: 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
eee0: 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
eef0: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
ef00: 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
ef10: 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
ef20: 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
ef30: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ef40: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
ef50: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ef60: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
ef70: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ef80: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
ef90: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
efa0: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
efb0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
efc0: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
efd0: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
efe0: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
eff0: 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
f000: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f010: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
f020: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
f030: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
f040: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
f050: 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
f060: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
f070: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f080: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
f090: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
f0a0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
f0b0: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
f0c0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
f0d0: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
f0e0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f0f0: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
f100: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
f110: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
f120: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
f130: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
f140: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
f150: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
f160: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
f170: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
f180: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
f190: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
f1a0: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
f1b0: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
f1c0: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
f1d0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f1e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f1f0: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
f200: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f210: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f220: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f230: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f240: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
f250: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
f260: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
f270: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
f280: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
f290: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
f2a0: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
f2b0: 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
f2c0: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
f2d0: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
f2e0: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
f2f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
f300: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
f310: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
f320: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
f330: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
f340: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
f350: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
f360: 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
f370: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
f380: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
f390: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
f3a0: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
f3b0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
f3c0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
f3d0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f3e0: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
f3f0: 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
f400: 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
f410: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
f420: 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
f430: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
f440: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
f450: 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
f460: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
f470: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
f480: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
f490: 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
f4a0: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
f4b0: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
f4c0: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
f4d0: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
f4e0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
f4f0: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
f500: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
f510: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f520: 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
f530: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f540: 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
f550: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
f560: 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
f570: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f580: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
f590: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f5a0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f5b0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f5c0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f5d0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f5e0: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
f5f0: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
f600: 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
f610: 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
f620: 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a  lemenation.  .**
f630: 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
f640: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
f650: 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
f660: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
f670: 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
f680: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
f690: 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
f6a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f6b0: 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  CACHE option..**
f6c0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
f6d0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
f6e0: 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
f6f0: 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
f700: 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
f710: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
f720: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
f730: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
f740: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
f750: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
f760: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
f770: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
f780: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
f790: 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
f7a0: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
f7b0: 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
f7c0: 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
f7d0: 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
f7e0: 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
f7f0: 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
f800: 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
f810: 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
f820: 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
f830: 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
f840: 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
f850: 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
f860: 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
f870: 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
f880: 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
f890: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
f8a0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
f8b0: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
f8c0: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
f8d0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
f8e0: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
f8f0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
f900: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
f910: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f920: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
f930: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
f940: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
f950: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
f960: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
f970: 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
f980: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
f990: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
f9a0: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
f9b0: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
f9c0: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
f9d0: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
f9e0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
f9f0: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
fa00: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
fa10: 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
fa20: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
fa30: 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
fa40: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
fa50: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
fa60: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
fa70: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
fa80: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
fa90: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
faa0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fab0: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
fac0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
fad0: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
fae0: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
faf0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
fb00: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
fb10: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
fb20: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
fb30: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
fb40: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
fb50: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
fb60: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
fb70: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
fb80: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
fb90: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
fba0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
fbb0: 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
fbc0: 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
fbd0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
fbe0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fbf0: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
fc00: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
fc10: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
fc20: 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
fc30: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
fc40: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
fc50: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
fc60: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
fc70: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
fc80: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
fc90: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
fca0: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
fcb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
fcc0: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
fcd0: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
fce0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
fcf0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
fd00: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
fd10: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
fd20: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
fd30: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
fd40: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
fd50: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
fd60: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
fd70: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
fd80: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
fd90: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
fda0: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
fdb0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
fdc0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fdd0: 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
fde0: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
fdf0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
fe00: 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
fe10: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
fe20: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
fe30: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
fe40: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
fe50: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
fe60: 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
fe70: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
fe80: 63 61 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20  capped at 2^12. 
fe90: 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
fea0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
feb0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
fec0: 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72  size are 2^5 thr
fed0: 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a  ough 2^8.</dd>.*
fee0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
fef0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
ff00: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
ff10: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
ff20: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ff30: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
ff40: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
ff50: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
ff60: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
ff70: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
ff80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
ff90: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
ffa0: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
ffb0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
ffc0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
ffd0: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
ffe0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
fff0: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
10000 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
10010 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
10020 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
10030 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
10040 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
10050 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
10060 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10070 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
10080 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10090 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
100a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
100b0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
100c0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
100d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
100e0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
100f0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
10100 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
10110 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
10120 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
10130 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
10140 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
10150 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
10160 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
10170 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
10180 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
10190 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
101a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
101b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
101c0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
101d0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
101e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
101f0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10200 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10210 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10220 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10230 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10240 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
10250 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10260 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10270 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10280 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
10290 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
102a0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
102b0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
102c0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
102d0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
102e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
102f0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
10300 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
10310 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
10320 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
10330 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
10340 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
10350 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
10360 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10370 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10380 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10390 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
103a0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
103b0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
103c0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
103d0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
103e0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
103f0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10400 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10410 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10420 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
10430 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10440 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
10450 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
10460 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10470 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10480 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
10490 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
104a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
104b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
104c0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
104d0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
104e0 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
104f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
10500 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
10510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10520 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
10530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10540 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
10550 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
10560 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
10570 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
10580 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
10590 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
105a0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
105b0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
105c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
105d0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
105e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
105f0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
10600 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
10610 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
10620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
10630 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
10640 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
10650 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
10660 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
10670 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
10680 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
10690 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
106a0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
106b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
106c0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
106d0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
106e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
106f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10700 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
10710 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
10720 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
10730 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
10740 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
10750 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
10760 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
10770 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
10780 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
10790 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
107a0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
107b0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
107c0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
107d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
107e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
107f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
10800 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10810 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10820 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10830 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10840 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
10860 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
10870 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
10880 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
10890 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
108a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
108b0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
108c0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
108d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
108e0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
108f0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
10900 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
10910 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
10920 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
10930 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
10940 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
10950 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
10960 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
10970 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
10980 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
10990 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
109a0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
109b0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
109c0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
109d0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
109e0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
109f0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
10a00 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
10a10 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
10a20 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
10a30 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
10a40 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
10a50 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
10a60 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
10a70 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10a80 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
10a90 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
10aa0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
10ab0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10ac0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
10ad0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10ae0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
10af0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
10b00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
10b10 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
10b20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
10b30 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
10b40 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
10b50 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
10b60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
10b70 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
10b80 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10b90 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
10ba0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
10bb0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
10bc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10bd0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
10be0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10bf0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
10c00 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
10c10 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
10c20 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
10c30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
10c40 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
10c50 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
10c60 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
10c70 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
10c80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
10c90 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
10ca0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
10cb0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
10cc0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10cd0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
10ce0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
10cf0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
10d00 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
10d10 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
10d20 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
10d30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
10d40 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
10d50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10d60 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
10d70 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10d80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10d90 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
10da0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
10db0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10dc0 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
10dd0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10df0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
10e00 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
10e10 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10e30 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
10e40 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
10e50 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
10e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10e70 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
10e80 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
10e90 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10eb0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
10ec0 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
10ed0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
10ee0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10ef0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
10f00 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
10f10 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
10f20 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
10f30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10f40 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
10f50 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
10f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10f70 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
10f80 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
10f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
10fa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10fb0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
10fc0 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
10fd0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10fe0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
10ff0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
11000 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
11010 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
11020 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
11030 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
11040 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
11050 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
11060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11070 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
11080 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
11090 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
110a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
110b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
110c0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
110d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
110e0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
110f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11100 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
11110 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
11120 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
11130 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
11140 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
11150 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
11160 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11170 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11180 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11190 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
111a0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
111b0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
111c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
111d0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
111e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
111f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11200 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11210 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11220 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
11230 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
11240 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
11250 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11260 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
11270 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
11280 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11290 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
112a0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
112b0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
112c0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
112d0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
112e0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
112f0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11300 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11310 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11320 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11330 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11340 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11350 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11360 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11370 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11380 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
11390 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
113a0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
113b0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
113c0 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
113d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
113e0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
113f0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
11400 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
11410 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
11420 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
11430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11440 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
11450 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
11460 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
11470 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11480 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
11490 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
114a0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
114b0 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
114c0 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
114d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
114e0 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
114f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11500 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
11510 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
11520 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
11530 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
11540 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
11550 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
11560 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11570 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
11580 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
11590 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
115a0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
115b0 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
115c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
115d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
115e0 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
115f0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
11600 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11610 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
11620 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
11630 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
11640 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
11650 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
11660 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
11670 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
11680 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11690 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
116a0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
116b0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
116c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
116d0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
116e0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
116f0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
11700 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
11710 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
11720 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
11730 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
11740 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
11750 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
11760 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
11770 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
11780 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
11790 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
117a0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
117b0 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
117c0 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
117d0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
117e0 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
117f0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
11800 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
11810 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
11820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11830 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
11840 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
11850 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
11860 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
11870 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
11880 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
11890 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
118a0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
118b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
118c0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
118d0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
118e0 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
118f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
11900 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
11910 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
11920 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
11930 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
11940 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
11950 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
11960 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
11970 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
11980 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
11990 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
119a0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
119b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
119c0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
119d0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
119e0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
119f0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
11a00 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
11a10 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
11a20 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
11a30 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
11a40 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
11a50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
11a60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11a70 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
11a80 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
11a90 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
11aa0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
11ab0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
11ac0 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
11ad0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
11ae0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
11af0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
11b00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
11b10 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
11b20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
11b30 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
11b40 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
11b50 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
11b60 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
11b70 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
11b80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11b90 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
11ba0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
11bb0 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
11bc0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
11bd0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
11be0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
11bf0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
11c00 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11c10 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
11c20 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
11c30 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
11c40 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
11c50 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
11c60 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
11c70 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
11c80 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
11c90 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
11ca0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
11cb0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
11cc0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
11cd0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
11ce0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
11cf0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
11d00 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
11d10 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
11d20 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
11d30 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
11d40 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
11d50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
11d60 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
11d70 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
11d80 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
11d90 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
11da0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
11db0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
11dc0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
11dd0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
11de0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
11df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
11e00 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
11e10 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
11e20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
11e30 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
11e40 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
11e50 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
11e60 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
11e70 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
11e80 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
11e90 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
11ea0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
11eb0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
11ec0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
11ed0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
11ee0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
11ef0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
11f00 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
11f10 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
11f20 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
11f30 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
11f40 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
11f50 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
11f60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
11f70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
11f80 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
11f90 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
11fa0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
11fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
11fc0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
11fd0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
11fe0 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
11ff0 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
12000 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
12010 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
12020 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
12030 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
12040 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
12050 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
12060 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
12070 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
12080 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
12090 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
120a0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
120b0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
120c0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
120d0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
120e0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
120f0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
12100 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
12110 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
12120 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
12130 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
12140 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
12150 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
12160 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
12170 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
12180 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
12190 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
121a0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
121b0 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
121c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
121d0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
121e0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
121f0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
12200 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
12210 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
12220 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
12230 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
12240 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
12250 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
12260 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
12270 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
12280 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
12290 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
122a0 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
122b0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
122c0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
122d0 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
122e0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
122f0 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
12300 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
12310 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
12320 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
12330 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
12340 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
12350 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
12360 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
12370 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
12380 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
12390 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
123a0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
123b0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
123c0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
123d0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
123e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
123f0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
12400 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
12410 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
12420 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
12430 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
12440 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
12450 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
12460 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
12470 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
12480 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
12490 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
124a0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
124b0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
124c0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
124d0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
124e0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
124f0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
12500 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
12510 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
12520 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
12530 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
12540 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
12550 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
12560 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
12570 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
12580 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
12590 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
125a0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
125b0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
125c0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
125d0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
125e0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
125f0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
12600 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
12610 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
12620 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
12630 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
12640 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
12650 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
12660 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
12670 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
12680 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12690 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
126a0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
126b0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
126c0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
126d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
126e0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
126f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
12700 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
12710 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
12720 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
12730 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
12740 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
12750 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
12760 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
12770 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12780 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
12790 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
127a0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
127b0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
127c0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
127d0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
127e0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
127f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
12800 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
12810 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
12830 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
12840 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
12850 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
12860 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
12870 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
12880 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
12890 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
128a0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
128b0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
128c0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
128d0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
128e0 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
128f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12900 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
12910 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12920 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
12930 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
12940 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
12950 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
12960 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
12970 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
12980 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
12990 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
129a0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
129b0 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
129c0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
129d0 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
129e0 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
129f0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
12a00 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
12a10 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
12a20 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
12a30 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
12a40 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
12a50 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
12a60 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
12a70 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
12a80 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
12a90 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
12aa0 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
12ab0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
12ac0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
12ad0 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
12ae0 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
12af0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
12b00 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
12b10 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
12b20 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
12b30 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
12b40 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
12b50 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
12b60 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
12b70 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
12b80 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
12b90 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
12ba0 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
12bb0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
12bc0 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
12bd0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
12be0 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
12bf0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
12c00 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
12c10 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
12c20 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
12c30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
12c40 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
12c50 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
12c60 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
12c70 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
12c80 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
12c90 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
12ca0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
12cb0 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
12cc0 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
12cd0 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
12ce0 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
12cf0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
12d00 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
12d10 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
12d20 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
12d30 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
12d40 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
12d50 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
12d60 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
12d70 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
12d80 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
12d90 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
12da0 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
12db0 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
12dc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
12dd0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
12de0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
12df0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
12e00 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
12e10 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
12e20 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
12e30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12e40 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12e50 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
12e60 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
12e70 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
12e80 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
12e90 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
12ea0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
12eb0 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
12ec0 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
12ed0 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
12ee0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
12ef0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
12f00 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
12f10 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
12f20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
12f30 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
12f40 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
12f50 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
12f60 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
12f70 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
12f80 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
12f90 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
12fa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
12fb0 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
12fc0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
12fd0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
12fe0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
12ff0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
13000 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
13010 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
13020 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
13030 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
13040 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
13050 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
13060 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
13070 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
13080 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
13090 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
130a0 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
130b0 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
130c0 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
130d0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
130e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
130f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
13100 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
13110 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
13120 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
13130 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
13140 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
13150 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
13160 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
13170 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
13180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13190 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
131a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
131b0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
131c0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
131d0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
131e0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
131f0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
13200 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
13210 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
13220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13230 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
13240 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
13250 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
13260 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
13270 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
13280 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
13290 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
132a0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
132b0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
132c0 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
132d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
132e0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
132f0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
13300 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
13310 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
13320 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
13330 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
13340 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
13350 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
13360 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
13370 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
13380 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
13390 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
133a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
133b0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
133c0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
133d0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
133e0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
133f0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
13400 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
13410 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
13420 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
13430 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
13440 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
13450 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
13460 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
13470 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
13480 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
13490 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
134a0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
134b0 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
134c0 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
134d0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
134e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
134f0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
13500 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
13510 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
13520 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
13530 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
13540 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
13550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
13560 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
13570 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
13580 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
13590 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
135a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
135b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
135c0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
135d0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
135e0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
135f0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
13600 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
13610 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
13620 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
13630 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
13640 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
13650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13660 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
13670 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
13680 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
13690 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
136a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
136b0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
136c0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
136d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
136e0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
136f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
13700 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
13710 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
13720 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
13730 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
13740 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
13750 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
13760 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
13770 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
13780 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
13790 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
137a0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
137b0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
137c0 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
137d0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
137e0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
137f0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
13800 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
13810 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
13820 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
13830 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
13840 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
13850 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
13860 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
13870 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
13880 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
13890 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
138a0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
138b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
138c0 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
138d0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
138e0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
138f0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
13900 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13910 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
13920 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
13930 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
13940 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
13950 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
13960 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
13970 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
13980 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
13990 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
139a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
139b0 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
139c0 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
139d0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
139e0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
139f0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
13a00 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
13a10 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
13a20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
13a30 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
13a40 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
13a50 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
13a60 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
13a70 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
13a80 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
13a90 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13aa0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
13ab0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
13ac0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
13ad0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
13ae0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
13af0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
13b00 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
13b10 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
13b20 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13b30 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
13b40 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
13b50 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
13b60 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
13b70 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
13b80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13b90 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
13ba0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
13bb0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
13bc0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
13bd0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
13be0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
13bf0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
13c00 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
13c10 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
13c20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
13c30 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
13c40 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
13c50 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
13c60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
13c70 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
13c80 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
13c90 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
13ca0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
13cb0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
13cc0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
13cd0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
13ce0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
13cf0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
13d00 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
13d10 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
13d20 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
13d30 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
13d40 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
13d50 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
13d60 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
13d70 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
13d80 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
13d90 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
13da0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
13db0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
13dc0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
13dd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
13de0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
13df0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
13e00 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
13e10 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
13e20 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
13e30 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
13e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
13e50 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
13e60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13e70 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
13e80 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
13e90 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
13ea0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13eb0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
13ec0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
13ed0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
13ee0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
13ef0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
13f00 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
13f10 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
13f20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
13f30 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
13f40 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
13f50 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
13f60 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
13f70 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
13f80 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
13f90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
13fa0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
13fb0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
13fc0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
13fd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
13fe0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
13ff0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
14000 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
14010 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
14020 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
14030 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
14040 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
14050 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
14060 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
14070 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
14080 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
14090 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
140a0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
140b0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
140c0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
140d0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
140e0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
140f0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
14100 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
14110 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
14120 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
14130 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
14140 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
14150 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
14160 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
14170 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
14180 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
14190 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
141a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
141b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
141c0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
141d0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
141e0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
141f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
14200 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
14210 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
14220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
14230 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
14240 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
14250 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
14260 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
14270 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
14280 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
14290 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
142a0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
142b0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
142c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
142d0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
142e0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
142f0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
14300 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
14310 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
14320 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
14330 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
14340 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
14350 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
14360 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
14370 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
14380 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
14390 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
143a0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
143b0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
143c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
143d0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
143e0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
143f0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
14400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
14410 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
14420 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
14430 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
14440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
14450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
14460 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
14470 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
14480 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
14490 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
144a0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
144b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
144c0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
144d0 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
144e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
144f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
14500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14510 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
14520 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
14530 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
14540 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
14550 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
14560 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
14570 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
14580 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
14590 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
145a0 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
145b0 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
145c0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
145d0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
145e0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
145f0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
14600 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
14610 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
14620 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
14630 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
14640 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
14650 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
14660 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
14670 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
14680 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
14690 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
146a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
146b0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
146c0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
146d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
146e0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
146f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
14700 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14710 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
14720 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
14730 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
14740 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14750 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
14760 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14770 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
14780 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
14790 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
147a0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
147b0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
147c0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
147d0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
147e0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
147f0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
14800 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
14810 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
14820 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
14830 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
14840 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
14850 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
14860 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
14870 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
14880 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
14890 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
148a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
148b0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
148c0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
148d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
148e0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
148f0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
14900 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
14910 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
14920 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
14930 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
14940 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
14950 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
14960 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
14970 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
14980 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
14990 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
149a0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
149b0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
149c0 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
149d0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
149e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
149f0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
14a00 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
14a10 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
14a20 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
14a30 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
14a40 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
14a50 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
14a60 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
14a70 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
14a80 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
14a90 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
14aa0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
14ab0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
14ac0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
14ad0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
14ae0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
14af0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
14b00 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
14b10 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
14b20 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
14b30 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
14b40 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
14b50 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
14b60 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
14b70 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
14b80 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
14b90 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
14ba0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
14bb0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
14bc0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
14bd0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
14be0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
14bf0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
14c00 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
14c10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
14c20 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
14c30 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
14c40 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
14c50 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
14c60 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
14c70 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
14c80 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
14c90 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
14ca0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
14cb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
14cc0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
14cd0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
14ce0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
14cf0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
14d00 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
14d10 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14d20 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
14d30 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
14d40 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
14d50 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
14d60 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
14d70 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
14d80 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
14d90 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
14da0 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
14db0 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
14dc0 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
14dd0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
14de0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
14df0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
14e00 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
14e10 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
14e20 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
14e30 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
14e40 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
14e50 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
14e60 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
14e70 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
14e80 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
14e90 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
14ea0 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
14eb0 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
14ec0 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
14ed0 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
14ee0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
14ef0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
14f00 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
14f10 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
14f20 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
14f30 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
14f40 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
14f50 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
14f60 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
14f70 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
14f80 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
14f90 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
14fa0 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
14fb0 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
14fc0 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
14fd0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
14fe0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
14ff0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
15000 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
15010 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
15020 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
15030 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
15040 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
15050 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
15060 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
15070 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
15080 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15090 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
150a0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
150b0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
150c0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
150d0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
150e0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
150f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
15100 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
15110 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
15120 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
15130 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
15140 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
15150 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
15160 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
15170 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
15180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15190 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
151a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
151b0 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
151c0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
151d0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
151e0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
151f0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
15200 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
15210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15220 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
15230 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
15240 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
15250 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
15260 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
15270 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
15280 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
15290 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
152a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
152b0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
152c0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
152d0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
152e0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
152f0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
15300 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
15310 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
15320 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
15330 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
15340 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
15350 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
15360 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
15370 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
15380 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
15390 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
153a0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
153b0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
153c0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
153d0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
153e0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
153f0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
15400 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
15410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
15420 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
15430 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
15440 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
15450 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
15460 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
15470 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
15480 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
15490 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
154a0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
154b0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
154c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
154d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
154e0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
154f0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
15500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15510 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
15520 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
15530 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
15540 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
15550 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
15560 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
15570 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
15580 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
15590 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
155a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
155b0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
155c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
155d0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
155e0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
155f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
15600 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
15610 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
15620 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
15630 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
15640 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
15650 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
15660 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15670 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
15680 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
15690 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
156a0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
156b0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
156c0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
156d0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
156e0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
156f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
15700 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
15710 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
15720 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
15730 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
15740 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
15750 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
15760 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
15770 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
15780 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
15790 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
157a0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
157b0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
157c0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
157d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
157e0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
157f0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
15800 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
15810 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
15820 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
15830 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
15840 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
15850 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
15860 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
15870 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
15880 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
15890 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
158a0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
158b0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
158c0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
158d0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
158e0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
158f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
15900 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
15910 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
15920 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
15930 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
15940 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
15950 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
15960 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
15970 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
15980 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
15990 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
159a0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
159b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
159c0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
159d0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
159e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
159f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
15a00 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
15a10 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
15a20 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
15a30 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
15a40 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
15a50 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
15a60 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
15a70 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
15a80 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
15a90 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
15aa0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
15ab0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
15ac0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
15ad0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
15ae0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
15af0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
15b00 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
15b10 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
15b20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
15b30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15b40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
15b50 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
15b60 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
15b70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15b80 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
15b90 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
15ba0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
15bb0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
15bc0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
15bd0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
15be0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15bf0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
15c00 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
15c10 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
15c20 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
15c30 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
15c40 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
15c50 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
15c60 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
15c70 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
15c80 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
15c90 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
15ca0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
15cb0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
15cc0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15cd0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15ce0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
15cf0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15d00 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
15d10 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15d20 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
15d30 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
15d40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15d50 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
15d60 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15d70 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
15d80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15d90 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
15da0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15db0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
15dc0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
15dd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
15de0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
15df0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
15e00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15e10 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
15e20 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
15e30 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
15e40 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
15e50 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
15e60 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
15e70 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
15e80 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
15e90 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
15ea0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
15eb0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
15ec0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
15ed0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
15ee0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
15ef0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
15f00 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
15f10 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
15f20 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
15f30 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
15f40 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
15f50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
15f60 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
15f70 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
15f80 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
15f90 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
15fa0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
15fb0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
15fc0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
15fd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15fe0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
15ff0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16000 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
16010 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16020 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
16030 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16040 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
16050 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
16060 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
16070 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
16080 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
16090 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
160a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
160b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
160c0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
160d0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
160e0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
160f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
16100 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
16110 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
16120 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
16130 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
16140 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
16150 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
16160 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
16170 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
16180 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
16190 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
161a0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
161b0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
161c0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
161d0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
161e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
161f0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
16200 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
16210 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
16220 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
16230 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
16240 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
16250 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
16260 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
16270 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
16280 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
16290 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
162a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
162b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
162c0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
162d0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
162e0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
162f0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
16300 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
16310 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
16320 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
16330 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
16340 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
16350 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
16360 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
16370 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
16380 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
16390 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
163a0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
163b0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
163c0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
163d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
163e0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
163f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16400 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
16410 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
16420 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
16430 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
16440 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
16450 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
16460 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
16470 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
16480 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
16490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
164a0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
164b0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
164c0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
164d0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
164e0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
164f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
16500 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
16510 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
16520 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
16530 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
16540 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
16550 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
16560 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
16570 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
16580 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
16590 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
165a0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
165b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
165c0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
165d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
165e0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
165f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
16600 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
16610 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
16620 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
16630 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
16640 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
16650 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
16660 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
16670 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
16680 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16690 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
166a0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
166b0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
166c0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
166d0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
166e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
166f0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
16700 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
16710 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
16720 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
16730 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
16740 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
16750 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
16760 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
16770 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
16780 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
16790 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
167a0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
167b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
167c0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
167d0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
167e0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
167f0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
16800 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
16810 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
16820 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
16830 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
16840 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
16850 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
16860 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
16870 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
16880 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
16890 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
168a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
168b0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
168c0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
168d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
168e0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
168f0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
16900 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
16910 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
16920 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
16930 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
16940 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
16950 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
16960 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
16970 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
16980 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
16990 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
169a0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
169b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
169c0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
169d0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
169e0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
169f0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
16a00 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
16a10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
16a20 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
16a30 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
16a40 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
16a50 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
16a60 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
16a70 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
16a80 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
16a90 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
16aa0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
16ab0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
16ac0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
16ad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
16ae0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
16af0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
16b00 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
16b10 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
16b20 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
16b30 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
16b40 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
16b50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
16b60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
16b70 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
16b80 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
16b90 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
16ba0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
16bb0 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
16bc0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
16bd0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
16be0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
16bf0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
16c00 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
16c10 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
16c20 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
16c30 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
16c40 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
16c50 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
16c60 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
16c70 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
16c80 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
16c90 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
16ca0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
16cb0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
16cc0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
16cd0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
16ce0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16cf0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16d00 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
16d10 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
16d20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16d30 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
16d40 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
16d50 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
16d60 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
16d70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16d80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
16d90 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
16da0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
16db0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
16dc0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
16dd0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
16de0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
16df0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
16e00 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
16e10 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16e20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
16e30 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
16e40 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
16e50 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
16e60 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
16e70 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
16e80 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
16e90 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
16ea0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16eb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
16ec0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
16ed0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
16ee0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
16ef0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16f00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
16f10 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
16f20 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
16f30 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
16f40 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
16f50 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
16f60 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
16f70 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16f80 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16f90 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16fa0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
16fb0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
16fc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16fd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
16fe0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
16ff0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
17000 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
17010 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
17020 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
17030 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
17040 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
17050 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
17060 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
17070 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
17080 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
17090 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
170a0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
170b0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
170c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
170d0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
170e0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
170f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
17100 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
17110 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
17120 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
17130 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
17140 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
17150 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
17160 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
17170 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
17180 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
17190 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
171a0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
171b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
171c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
171d0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
171e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
171f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
17200 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17210 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
17220 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17230 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
17240 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
17250 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
17260 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
17270 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
17280 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
17290 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
172a0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
172b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
172c0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
172d0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
172e0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
172f0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
17300 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
17310 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
17320 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
17330 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
17340 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
17350 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
17360 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
17370 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
17380 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
17390 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
173a0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
173b0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
173c0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
173d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
173e0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
173f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
17400 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
17410 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
17420 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
17430 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
17440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17450 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
17460 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
17470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
17480 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
17490 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
174a0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
174b0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
174c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
174d0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
174e0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
174f0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
17500 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
17510 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
17520 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
17530 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
17540 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
17550 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
17560 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
17570 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
17580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17590 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
175a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
175b0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
175c0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
175d0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
175e0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
175f0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
17600 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
17610 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
17620 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
17630 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
17640 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
17650 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
17660 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
17670 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
17680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17690 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
176a0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
176b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
176c0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
176d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
176e0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
176f0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
17700 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
17710 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
17720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
17730 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17740 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
17750 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
17760 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
17770 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
17780 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
17790 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
177a0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
177b0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
177c0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
177d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
177e0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
177f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
17800 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
17810 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
17820 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
17830 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
17840 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
17850 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
17860 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
17870 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
17880 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
17890 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
178a0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
178b0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
178c0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
178d0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
178e0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
178f0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
17900 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
17910 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
17920 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
17930 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
17940 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
17950 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
17960 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
17970 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
17980 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
17990 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
179a0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
179b0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
179c0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
179d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
179e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
179f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
17a00 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
17a10 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
17a20 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
17a30 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
17a40 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
17a50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17a60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
17a70 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
17a80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
17a90 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
17aa0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
17ab0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
17ac0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
17ad0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
17ae0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
17af0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
17b00 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
17b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
17b20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
17b30 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
17b40 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
17b50 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
17b60 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
17b70 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17b80 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
17b90 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
17ba0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
17bb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
17bc0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
17bd0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
17be0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
17bf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
17c00 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
17c10 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
17c20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
17c30 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
17c40 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
17c50 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
17c60 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
17c70 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
17c80 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
17c90 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
17ca0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
17cb0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
17cc0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
17cd0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
17ce0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17cf0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
17d00 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
17d10 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
17d20 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
17d30 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
17d40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17d50 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
17d60 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
17d70 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
17d80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
17d90 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
17da0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
17db0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
17dc0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
17dd0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
17de0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
17df0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
17e00 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
17e10 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
17e20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
17e30 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
17e40 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
17e50 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
17e60 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
17e70 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
17e80 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
17e90 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
17ea0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
17eb0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
17ec0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
17ed0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
17ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
17ef0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
17f00 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
17f10 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
17f20 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
17f30 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
17f40 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
17f50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
17f60 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
17f70 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
17f80 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
17f90 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
17fa0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
17fb0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
17fc0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
17fd0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
17fe0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
17ff0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
18000 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
18010 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
18020 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
18030 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
18040 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
18050 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
18060 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
18070 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
18080 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
18090 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
180a0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
180b0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
180c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
180d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
180e0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
180f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
18110 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
18120 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
18130 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
18140 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
18150 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
18160 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
18170 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
18180 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18190 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
181a0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
181b0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
181c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
181d0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
181e0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
181f0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
18200 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
18210 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
18220 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
18230 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
18240 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
18250 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
18260 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
18270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
18280 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
18290 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
182a0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
182b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
182c0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
182d0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
182e0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
182f0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18300 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18310 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
18320 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
18330 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
18340 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
18350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
18360 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
18370 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
18380 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
18390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
183a0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
183b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
183c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
183d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
183e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
183f0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
18400 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
18410 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
18420 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
18430 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
18440 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18450 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
18460 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
18470 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
18480 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18490 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
184a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
184b0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
184c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
184d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
184e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
184f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
18500 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18510 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
18520 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
18530 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
18540 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
18550 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
18560 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
18570 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
18580 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
18590 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
185a0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
185b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
185c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
185d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
185e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
185f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
18600 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
18610 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
18620 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
18630 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
18640 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
18650 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
18660 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18670 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
18680 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
18690 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
186a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
186b0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
186c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
186d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
186e0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
186f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
18700 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
18710 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
18720 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
18730 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
18740 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
18750 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
18760 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
18770 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
18780 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
18790 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
187a0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
187b0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
187c0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
187d0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
187e0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
187f0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
18800 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
18810 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
18820 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
18830 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
18840 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
18850 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
18860 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
18870 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
18880 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
18890 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
188a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
188b0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
188c0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
188d0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
188e0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
188f0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
18900 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
18910 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
18920 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
18930 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
18940 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
18950 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
18960 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
18970 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
18980 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
18990 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
189a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
189b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
189c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
189d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
189e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
189f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
18a00 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
18a10 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
18a20 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
18a30 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
18a40 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
18a50 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
18a60 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
18a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
18a80 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
18a90 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
18aa0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
18ab0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
18ac0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
18ad0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
18ae0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
18af0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
18b00 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18b10 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
18b20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18b30 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
18b40 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
18b50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
18b60 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
18b70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
18b80 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
18b90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18ba0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
18bb0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
18bc0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
18bd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
18be0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
18bf0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
18c00 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
18c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
18c20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
18c30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
18c40 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
18c50 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
18c60 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
18c70 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
18c80 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
18c90 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
18ca0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
18cb0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
18cc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18cd0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
18ce0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
18cf0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
18d00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18d10 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
18d20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
18d30 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
18d40 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
18d50 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
18d60 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
18d70 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
18d80 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
18d90 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
18da0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
18db0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
18dc0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
18dd0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
18de0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
18df0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
18e00 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
18e10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18e20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18e30 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
18e40 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
18e50 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
18e60 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
18e70 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
18e80 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
18e90 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
18ea0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
18eb0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
18ec0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
18ed0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
18ee0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
18ef0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
18f00 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
18f10 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
18f20 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
18f30 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
18f40 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
18f50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
18f60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
18f70 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
18f80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18f90 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
18fa0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
18fb0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
18fc0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
18fd0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
18fe0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
18ff0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
19000 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
19010 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
19020 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
19030 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19040 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
19050 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
19060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
19070 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19080 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
19090 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
190a0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
190b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
190c0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
190d0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
190e0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
190f0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
19100 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
19110 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
19120 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
19130 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
19140 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
19150 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
19160 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
19170 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
19180 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
19190 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
191a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
191b0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
191c0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
191d0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
191e0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
191f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
19200 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
19210 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
19220 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
19230 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
19240 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
19250 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
19260 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
19270 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
19280 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
19290 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
192a0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
192b0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
192c0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
192d0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
192e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
192f0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
19300 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
19310 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
19320 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
19330 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
19340 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
19350 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
19360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
19370 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
19380 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
19390 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
193a0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
193b0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
193c0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
193d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
193e0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
193f0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
19400 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
19410 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
19420 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
19430 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
19440 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
19450 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
19460 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
19470 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
19480 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19490 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
194a0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
194b0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
194c0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
194d0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
194e0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
194f0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
19500 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
19510 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
19520 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
19530 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
19540 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
19550 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
19560 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
19570 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
19580 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
19590 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
195a0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
195b0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
195c0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
195d0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
195e0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
195f0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
19600 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
19610 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
19620 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
19630 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
19640 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
19650 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
19660 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
19670 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
19680 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
19690 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
196a0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
196b0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
196c0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
196d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
196e0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
196f0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
19700 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
19710 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
19720 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
19730 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
19740 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
19750 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
19760 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
19770 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
19780 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
19790 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
197a0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
197b0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
197c0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
197d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
197e0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
197f0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
19800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19810 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
19820 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
19830 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
19840 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
19850 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
19860 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
19870 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
19880 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19890 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
198a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
198b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
198c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
198d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
198e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
198f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
19900 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19910 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
19920 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
19930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
19940 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
19950 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
19960 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
19970 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
19980 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
19990 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
199a0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
199b0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
199c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
199d0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
199e0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
199f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
19a00 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
19a10 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
19a20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
19a30 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
19a40 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
19a50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
19a60 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
19a70 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
19a80 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
19a90 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
19aa0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
19ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
19ac0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
19ad0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
19ae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
19af0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
19b00 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
19b10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
19b20 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
19b30 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
19b40 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
19b50 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
19b60 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
19b70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
19b80 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
19b90 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
19ba0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
19bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
19bc0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
19bd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
19be0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
19bf0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
19c00 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
19c10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
19c20 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
19c30 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
19c40 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
19c50 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
19c60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
19c70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
19c80 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
19c90 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
19ca0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
19cb0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
19cc0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
19cd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19ce0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
19cf0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
19d00 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
19d10 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
19d20 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
19d30 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
19d40 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
19d50 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
19d60 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
19d70 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
19d80 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
19d90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
19da0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
19db0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
19dc0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
19dd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
19de0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
19df0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
19e00 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
19e10 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19e20 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
19e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19e40 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
19e50 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
19e60 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
19e70 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
19e80 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
19e90 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
19ea0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
19eb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
19ec0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
19ed0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
19ee0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
19ef0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
19f00 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
19f10 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
19f20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
19f30 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
19f40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19f50 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
19f60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
19f70 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
19f80 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
19f90 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
19fa0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
19fb0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
19fc0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
19fd0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
19fe0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
19ff0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1a000 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1a010 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1a020 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1a030 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1a040 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1a050 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1a060 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1a070 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1a080 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1a090 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1a0a0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1a0b0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1a0c0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1a0d0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1a0e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a0f0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1a100 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a110 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1a120 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1a130 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1a140 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1a150 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1a160 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1a170 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1a180 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1a190 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1a1a0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1a1b0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1a1c0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1a1d0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1a1e0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1a1f0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1a200 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1a210 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1a220 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1a230 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1a240 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1a250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a260 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a270 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1a280 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1a290 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1a2a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1a2b0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1a2c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1a2d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1a2e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a2f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1a300 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1a310 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a320 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a330 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a340 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1a350 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1a360 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1a370 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a390 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1a3a0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1a3b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a3c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a3d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a3e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1a3f0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1a400 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1a410 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a430 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1a440 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1a450 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1a460 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a480 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1a490 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1a4a0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1a4b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a4c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a4d0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1a4e0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1a4f0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1a500 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a520 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1a530 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1a540 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1a550 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1a570 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1a580 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1a590 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1a5a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1a5b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1a5c0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1a5d0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1a5e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1a5f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a600 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1a610 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1a620 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1a630 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1a640 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1a650 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1a660 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1a670 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1a680 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a690 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a6a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1a6b0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1a6c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1a6d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1a6e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a6f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1a700 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1a710 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1a720 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a730 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a740 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1a750 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1a760 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1a770 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a780 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a790 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1a7a0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1a7b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1a7c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a7d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a7e0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1a7f0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1a800 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a810 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a820 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a830 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1a840 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1a850 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1a860 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1a870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a880 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1a890 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1a8a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a8b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1a8c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a8d0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1a8e0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1a8f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1a900 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a920 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1a930 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1a940 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1a950 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a970 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1a980 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1a990 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1a9a0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1a9b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1a9c0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1a9d0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1a9e0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1a9f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1aa00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1aa10 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1aa20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1aa30 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1aa40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1aa50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1aa60 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1aa70 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1aa80 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1aa90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1aaa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1aab0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1aac0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1aad0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1aae0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1aaf0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1ab00 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1ab10 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1ab20 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ab30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ab40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ab50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1ab60 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1ab70 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ab80 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ab90 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1aba0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1abb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1abc0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1abd0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1abe0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1abf0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1ac00 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1ac10 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1ac20 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1ac30 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1ac40 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1ac50 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1ac60 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1ac70 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1ac80 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1ac90 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1aca0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1acb0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1acc0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1acd0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1ace0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1acf0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1ad00 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1ad10 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1ad20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1ad30 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1ad40 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1ad50 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1ad60 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1ad70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ad80 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1ad90 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ada0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1adb0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1adc0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1add0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1ade0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1adf0 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1ae00 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ae10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ae20 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1ae30 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1ae40 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1ae50 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1ae60 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1ae70 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1ae80 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1ae90 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1aea0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1aeb0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1aec0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1aed0 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1aee0 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1aef0 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1af00 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1af10 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1af20 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1af30 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1af40 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1af50 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1af60 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1af70 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1af80 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1af90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1afa0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1afb0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1afc0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1afd0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1afe0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1aff0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1b000 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1b010 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1b020 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1b030 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1b040 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1b050 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1b060 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1b070 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1b080 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1b090 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1b0a0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1b0b0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1b0c0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1b0d0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1b0e0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1b0f0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1b100 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1b110 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1b120 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1b130 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1b140 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1b150 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1b160 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1b170 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1b180 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1b190 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1b1a0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1b1b0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1b1c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1b1d0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
1b1e0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1b1f0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1b200 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1b210 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1b220 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1b230 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1b240 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1b250 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1b260 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1b270 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1b280 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1b290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b2a0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1b2b0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1b2c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1b2d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1b2e0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1b2f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1b300 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1b310 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1b320 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1b330 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1b340 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1b350 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b360 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b370 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b380 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1b390 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b3a0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1b3b0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1b3c0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1b3d0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1b3e0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1b3f0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1b400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1b410 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1b420 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1b430 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1b440 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1b450 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1b460 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1b470 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b480 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1b490 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1b4a0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1b4b0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1b4c0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1b4d0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1b4e0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1b4f0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1b500 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1b510 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1b520 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1b530 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b540 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1b550 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1b560 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1b570 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1b580 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1b590 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1b5a0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1b5b0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1b5c0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1b5d0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1b5e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1b5f0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1b600 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1b610 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b620 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1b630 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b640 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1b650 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1b660 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1b670 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1b680 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1b690 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1b6a0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1b6b0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1b6c0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1b6d0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1b6e0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b6f0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b700 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b720 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b730 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1b740 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1b750 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1b760 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1b770 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b780 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1b790 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1b7a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1b7b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1b7c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1b7d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
1b7e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1b7f0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1b800 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1b810 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1b820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b830 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1b840 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1b850 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1b860 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1b870 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1b880 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
1b890 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ame is given by 
1b8a0 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
1b8b0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1b8c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1b8d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1b8e0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1b8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b900 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b910 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1b920 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1b930 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1b940 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1b950 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1b960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1b970 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1b980 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1b990 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1b9a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1b9b0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1b9c0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1b9d0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1b9e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1b9f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ba00 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ba10 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1ba20 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1ba30 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1ba40 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1ba50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1ba60 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1ba70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1ba80 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1ba90 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1baa0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1bab0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1bac0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1bad0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1bae0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1baf0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1bb00 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1bb10 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1bb20 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1bb30 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1bb40 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1bb50 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1bb60 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1bb70 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1bb80 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1bb90 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1bba0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1bbb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1bbc0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1bbd0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1bbe0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1bbf0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1bc00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1bc10 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1bc20 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1bc30 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1bc40 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1bc50 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1bc60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1bc70 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1bc80 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1bc90 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1bca0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1bcb0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1bcc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bcd0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1bce0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1bcf0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1bd00 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1bd10 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1bd20 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1bd30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1bd40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1bd50 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1bd60 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1bd70 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1bd80 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1bd90 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1bda0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1bdb0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1bdc0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1bdd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bde0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1bdf0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1be00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1be10 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1be20 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1be30 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1be40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1be50 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1be60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1be70 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1be80 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1be90 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1bea0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1beb0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1bec0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1bed0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1bee0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1bef0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1bf00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1bf10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1bf20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1bf30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1bf40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1bf50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1bf60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1bf70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1bf80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1bf90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1bfa0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1bfb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1bfc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1bfd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1bfe0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1bff0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1c000 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1c010 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1c020 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1c030 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1c040 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1c050 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1c060 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1c070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1c080 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1c090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c0a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1c0b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1c0c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c0d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1c0e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1c0f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1c100 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1c110 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1c120 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1c130 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1c140 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1c150 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1c160 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1c170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1c180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1c190 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1c1a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1c1b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1c1c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c1d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1c1e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1c1f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1c200 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1c210 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1c220 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1c230 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1c240 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c250 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c260 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
1c270 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1c280 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
1c290 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1c2a0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1c2b0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s,.** then the b
1c2c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1c2d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1c2e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1c2f0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1c300 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1c310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c320 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1c330 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1c340 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1c350 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1c360 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1c370 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1c380 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1c390 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1c3a0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1c3b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1c3c0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1c3d0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1c3e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c3f0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1c400 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1c410 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1c420 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1c430 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1c440 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1c450 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1c460 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1c470 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1c480 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1c490 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1c4a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c4b0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1c4c0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1c4d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1c4e0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1c4f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1c500 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1c510 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1c520 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1c530 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1c540 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1c550 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1c560 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1c570 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1c580 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1c590 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1c5a0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1c5b0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1c5c0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1c5d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1c5e0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1c5f0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1c600 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1c610 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1c620 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1c630 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1c640 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1c650 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1c660 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1c670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c680 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1c690 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1c6a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1c6b0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1c6c0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1c6d0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1c6e0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1c6f0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1c700 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1c710 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1c720 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1c730 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1c740 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1c750 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1c760 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1c770 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1c780 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1c790 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1c7a0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1c7b0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1c7c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1c7d0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1c7e0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1c7f0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1c800 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1c810 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1c820 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1c830 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1c840 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c850 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1c860 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1c870 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1c880 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  losed..**.** ^Th
1c890 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1c8a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1c8b0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1c8c0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1c8d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c8e0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1c8f0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1c900 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1c910 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1c920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c930 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1c940 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1c950 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1c960 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1c970 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1c980 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1c990 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1c9a0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1c9b0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1c9c0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1c9d0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1c9e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1c9f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1ca00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1ca10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1ca20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1ca30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1ca40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1ca50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1ca60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1ca70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1ca80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1ca90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1caa0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1cab0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1cac0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cad0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1cae0 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  _v2()..*/.int sq
1caf0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1cb00 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1cb10 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1cb20 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cb30 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1cb40 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1cb50 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1cb60 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1cb70 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1cb80 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1cb90 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1cba0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1cbb0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1cbc0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1cbd0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1cbe0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1cbf0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1cc00 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1cc10 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1cc20 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1cc30 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cc40 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1cc50 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1cc60 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1cc70 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1cc80 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1cc90 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1cca0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1ccb0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1ccc0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1ccd0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1cce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ccf0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1cd00 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1cd10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1cd20 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1cd30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1cd40 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1cd50 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1cd60 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1cd70 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1cd80 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1cd90 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1cda0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1cdb0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1cdc0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1cdd0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1cde0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1cdf0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1ce00 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1ce10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1ce20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1ce30 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1ce40 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1ce50 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1ce60 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1ce70 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1ce80 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1ce90 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1cea0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1ceb0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1cec0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1ced0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1cee0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1cef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cf00 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1cf10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1cf20 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1cf30 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1cf40 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1cf50 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1cf60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1cf70 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1cf80 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1cf90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1cfa0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1cfb0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1cfc0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1cfd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1cfe0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1cff0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1d000 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1d010 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1d020 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1d030 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1d040 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1d050 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1d060 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1d070 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1d080 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1d090 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1d0a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1d0b0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1d0c0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1d0d0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1d0e0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1d0f0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1d100 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1d110 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1d120 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1d130 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1d140 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1d150 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1d160 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1d170 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1d180 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1d190 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1d1a0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1d1b0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1d1c0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1d1d0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1d1e0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1d1f0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1d200 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1d210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d220 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1d230 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1d240 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1d250 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1d260 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1d270 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1d280 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1d290 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1d2a0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1d2b0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1d2c0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1d2d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1d2e0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1d2f0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1d300 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1d310 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1d320 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1d330 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1d340 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1d350 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1d360 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1d370 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1d380 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1d390 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1d3a0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1d3b0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
1d3c0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1d3d0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1d3e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1d3f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1d400 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1d410 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1d420 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1d430 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1d440 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1d450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d460 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1d470 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1d480 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1d490 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1d4a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1d4b0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1d4c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1d4d0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1d4e0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1d4f0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1d500 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1d510 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1d520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1d530 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1d540 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1d550 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1d560 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1d570 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1d580 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1d590 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1d5a0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1d5b0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1d5c0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1d5d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d5e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d5f0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1d600 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1d610 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1d620 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1d630 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1d640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1d650 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1d660 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1d670 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1d680 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1d690 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1d6a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1d6b0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1d6c0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1d6d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1d6e0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1d6f0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1d700 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1d710 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1d720 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1d730 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1d740 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1d750 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1d760 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1d770 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1d780 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1d790 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1d7a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1d7b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1d7c0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1d7d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1d7e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1d7f0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
1d800 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
1d810 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1d820 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1d830 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1d840 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1d850 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1d860 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1d870 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1d880 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1d890 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d8a0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1d8b0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1d8c0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1d8d0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1d8e0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1d8f0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1d900 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1d910 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1d920 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1d930 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1d940 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1d950 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1d960 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1d970 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
1d980 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1d990 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1d9a0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1d9b0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1d9c0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
1d9d0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
1d9e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
1d9f0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
1da00 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1da10 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1da20 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
1da30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
1da40 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1da50 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
1da60 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1da70 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
1da80 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1da90 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1daa0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1dab0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1dac0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1dad0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1dae0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1daf0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1db00 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1db10 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1db20 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1db30 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
1db40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1db50 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
1db60 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
1db70 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
1db80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1db90 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
1dba0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
1dbb0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
1dbc0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
1dbd0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
1dbe0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
1dbf0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
1dc00 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
1dc10 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
1dc20 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
1dc30 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
1dc40 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1dc50 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1dc60 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1dc70 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1dc80 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1dc90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1dca0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1dcb0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1dcc0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1dcd0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1dce0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1dcf0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1dd00 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1dd10 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1dd20 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1dd30 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1dd40 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1dd50 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1dd60 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1dd70 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1dd80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1dd90 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1dda0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1ddb0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1ddc0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1ddd0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1dde0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1ddf0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1de00 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1de10 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1de20 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1de30 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1de40 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1de50 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1de60 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1de70 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1de80 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1de90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1dea0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1deb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1dec0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1ded0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1dee0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1def0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1df00 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1df10 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1df20 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1df30 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1df40 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1df50 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1df60 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1df70 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1df80 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1df90 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1dfa0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1dfb0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1dfc0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1dfd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1dfe0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1dff0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1e000 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1e010 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1e020 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1e030 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1e040 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1e050 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1e060 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1e070 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1e080 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1e090 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1e0a0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1e0b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1e0c0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1e0d0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1e0e0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1e0f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1e100 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1e110 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1e120 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1e130 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1e140 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1e150 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1e160 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1e170 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1e180 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1e190 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
1e1a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e1b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1e1c0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1e1d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e1e0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1e1f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1e200 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1e210 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e220 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1e230 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e240 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1e250 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1e260 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1e270 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1e280 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1e290 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1e2a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1e2b0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1e2c0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1e2d0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1e2e0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1e2f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e300 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1e310 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1e320 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1e330 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1e340 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1e350 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1e360 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e370 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1e380 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1e390 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e3a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1e3b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1e3c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1e3d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e3e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1e3f0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1e400 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e410 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1e420 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1e430 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1e440 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1e450 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1e460 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
1e470 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
1e480 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
1e490 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
1e4a0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
1e4b0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
1e4c0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
1e4d0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
1e4e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1e4f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1e500 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e510 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e520 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1e530 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1e540 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e550 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1e560 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1e570 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1e580 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1e590 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1e5a0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1e5b0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e5c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1e5d0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1e5e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e5f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1e600 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1e610 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1e620 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1e630 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1e640 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e650 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1e660 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1e670 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
1e680 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
1e690 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
1e6a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e6b0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  nt.)^.**.** ^(<d
1e6c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
1e6d0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
1e6e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e6f0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
1e700 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
1e710 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
1e720 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1e730 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
1e740 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1e750 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
1e760 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
1e770 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
1e780 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
1e790 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e7a0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
1e7b0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
1e7c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e7d0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
1e7e0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
1e7f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e800 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1e810 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
1e820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e830 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
1e840 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
1e850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e860 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1e870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
1e880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e890 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
1e8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
1e8b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e8c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1e8d0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
1e8e0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
1e8f0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1e900 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
1e910 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
1e920 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1e930 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1e940 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
1e950 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1e960 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
1e970 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1e980 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1e990 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
1e9a0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1e9b0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1e9c0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1e9d0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1e9e0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1e9f0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1ea00 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
1ea10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ea20 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
1ea30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ea40 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
1ea50 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
1ea60 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1ea70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ea80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ea90 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
1eaa0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
1eab0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
1eac0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
1ead0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
1eae0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1eaf0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
1eb00 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
1eb10 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1eb20 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
1eb30 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
1eb40 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
1eb50 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1eb60 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
1eb70 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
1eb80 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
1eb90 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
1eba0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
1ebb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1ebc0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
1ebd0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
1ebe0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1ebf0 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
1ec00 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
1ec10 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1ec20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
1ec30 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
1ec40 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1ec50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1ec60 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1ec70 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1ec80 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1ec90 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
1eca0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1ecb0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1ecc0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1ecd0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1ece0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1ecf0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1ed00 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1ed10 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1ed20 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1ed30 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1ed40 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1ed50 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1ed60 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1ed70 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1ed80 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1ed90 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1eda0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1edb0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1edc0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1edd0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1ede0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1edf0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1ee00 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1ee10 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1ee20 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1ee30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
1ee40 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
1ee50 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
1ee60 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1ee70 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
1ee80 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
1ee90 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1eea0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1eeb0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1eec0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
1eed0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
1eee0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1eef0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1ef00 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
1ef10 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
1ef20 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1ef30 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
1ef40 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
1ef50 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
1ef60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1ef70 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
1ef80 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
1ef90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
1efa0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
1efb0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
1efc0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
1efd0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
1efe0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1eff0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1f000 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1f010 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1f020 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1f030 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1f040 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1f050 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1f060 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1f070 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1f080 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1f090 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1f0a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1f0b0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1f0c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1f0d0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1f0e0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1f0f0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
1f100 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1f110 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
1f120 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1f130 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
1f140 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1f150 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1f160 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1f170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f180 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1f190 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1f1a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1f1b0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1f1c0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1f1d0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1f1e0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1f1f0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1f200 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1f210 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1f220 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1f230 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
1f240 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1f250 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1f260 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1f270 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1f280 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f290 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1f2a0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1f2b0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1f2c0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1f2d0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1f2e0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1f2f0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1f300 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1f310 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
1f320 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1f330 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
1f340 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
1f350 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
1f360 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
1f370 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
1f380 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
1f390 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
1f3a0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
1f3b0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1f3c0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
1f3d0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
1f3e0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
1f3f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1f400 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1f410 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1f420 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1f430 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1f440 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1f450 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1f460 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1f470 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1f480 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1f490 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1f4a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1f4b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1f4c0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1f4d0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1f4e0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1f4f0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1f500 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1f510 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1f520 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1f530 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1f540 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1f550 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1f560 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1f570 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1f580 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1f590 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1f5a0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1f5b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1f5c0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1f5d0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1f5e0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
1f5f0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
1f600 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
1f610 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1f620 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
1f630 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
1f640 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
1f650 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
1f660 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1f670 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
1f680 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
1f690 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1f6a0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
1f6b0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
1f6c0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
1f6d0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
1f6e0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
1f6f0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1f700 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
1f710 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1f720 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
1f730 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
1f740 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
1f750 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
1f760 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
1f770 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
1f780 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
1f790 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
1f7a0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
1f7b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
1f7c0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
1f7d0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
1f7e0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
1f7f0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
1f800 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
1f810 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
1f820 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
1f830 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
1f840 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69  BLE_STAT2] compi
1f850 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
1f860 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
1f870 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
1f880 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
1f890 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
1f8a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f8b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1f8c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1f8d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1f8e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1f8f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1f900 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f910 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f920 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f930 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f940 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f950 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f960 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f970 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f980 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1f990 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f9a0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f9b0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f9c0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1f9d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f9e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1f9f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1fa00 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1fa10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1fa20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1fa30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1fa40 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1fa50 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1fa60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1fa70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1fa80 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1fa90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1faa0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1fab0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1fac0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1fad0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1fae0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1faf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1fb00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1fb10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1fb20 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
1fb30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1fb40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1fb50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1fb60 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1fb70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1fb80 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1fb90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1fba0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1fbb0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1fbc0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1fbd0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1fbe0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1fbf0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1fc00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1fc10 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1fc20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1fc30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1fc40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1fc50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1fc60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1fc70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1fc80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1fc90 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1fca0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1fcb0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1fcc0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1fcd0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1fce0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1fcf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1fd00 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1fd10 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1fd20 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1fd30 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1fd40 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1fd50 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1fd60 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1fd70 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1fd80 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1fd90 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1fda0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fdb0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1fdc0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
1fdd0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
1fde0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
1fdf0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
1fe00 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
1fe10 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
1fe20 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
1fe30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fe40 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
1fe50 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
1fe60 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1fe70 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1fe80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1fe90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fea0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
1feb0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fec0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
1fed0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1fee0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1fef0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1ff00 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
1ff10 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
1ff20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ff30 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
1ff40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1ff50 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
1ff60 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
1ff70 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
1ff80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
1ff90 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
1ffa0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
1ffb0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
1ffc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
1ffd0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1ffe0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1fff0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
20000 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
20010 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
20020 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
20030 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
20040 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
20050 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
20060 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
20070 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
20080 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
20090 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
200a0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
200b0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
200c0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
200d0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
200e0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
200f0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
20100 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
20110 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
20120 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
20130 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
20140 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
20150 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
20160 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
20170 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
20180 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
20190 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
201a0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
201b0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
201c0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
201d0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
201e0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
201f0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
20200 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
20210 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
20220 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
20230 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
20240 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
20250 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
20260 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
20270 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
20280 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
20290 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
202a0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
202b0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
202c0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
202d0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
202e0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
202f0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
20300 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
20310 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
20320 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
20330 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
20340 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
20350 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
20360 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
20370 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
20380 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
20390 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
203a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
203b0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
203c0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
203d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
203e0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
203f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
20400 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
20410 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
20420 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
20430 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
20440 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
20450 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
20460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
20470 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
20480 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
20490 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
204a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
204b0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
204c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
204d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
204e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
204f0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
20500 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
20510 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
20520 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
20530 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
20540 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
20550 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
20560 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
20570 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
20580 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
20590 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
205a0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
205b0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
205c0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
205d0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
205e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
205f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20600 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
20610 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
20620 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
20630 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
20640 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
20650 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20660 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
20670 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
20680 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
20690 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
206a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
206b0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
206c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
206d0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
206e0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
206f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
20700 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
20710 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
20720 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
20740 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
20750 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
20760 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
20770 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
20780 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
20790 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
207a0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
207b0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
207c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
207d0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
207e0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
207f0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20800 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
20810 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
20820 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
20830 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
20840 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
20850 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
20860 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
20870 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
20880 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
20890 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
208a0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
208b0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
208c0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
208d0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
208e0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
208f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
20900 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
20910 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
20920 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
20930 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
20940 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
20950 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
20960 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
20970 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
20980 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
20990 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
209a0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
209b0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
209c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
209d0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
209e0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
209f0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
20a00 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
20a10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20a20 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
20a30 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
20a40 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
20a50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
20a60 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
20a70 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
20a80 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
20a90 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
20aa0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
20ab0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
20ac0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
20ad0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
20ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20af0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
20b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
20b10 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
20b20 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
20b30 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
20b40 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20b50 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
20b60 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
20b70 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
20b80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20b90 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
20ba0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
20bb0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
20bc0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
20bd0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
20be0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
20bf0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
20c00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20c10 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
20c20 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
20c30 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
20c40 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
20c50 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
20c60 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
20c70 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
20c80 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
20c90 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
20ca0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
20cb0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
20cc0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
20cd0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
20ce0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
20cf0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
20d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
20d10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20d20 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
20d30 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
20d40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20d50 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
20d60 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
20d70 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
20d80 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
20d90 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20da0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
20db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
20dc0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
20dd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
20de0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
20df0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
20e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
20e10 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
20e20 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
20e30 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
20e40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
20e50 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
20e60 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20e70 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
20e80 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
20e90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
20ea0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
20eb0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20ec0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
20ed0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
20ee0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20ef0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
20f00 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
20f10 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
20f20 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
20f30 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
20f40 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
20f50 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
20f60 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
20f70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
20f80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20f90 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
20fa0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
20fb0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
20fc0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
20fd0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
20fe0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
20ff0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
21000 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
21010 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
21020 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
21030 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
21040 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
21050 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
21060 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
21070 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
21080 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
21090 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
210a0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
210b0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
210c0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
210d0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
210e0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
210f0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
21100 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
21110 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
21120 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
21130 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
21140 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
21150 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
21160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21170 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
21180 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21190 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
211a0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
211b0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
211c0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
211d0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
211e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
211f0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
21200 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
21210 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
21220 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
21230 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
21240 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
21250 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
21260 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
21270 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
21280 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
21290 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
212a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
212b0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
212c0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
212d0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
212e0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
212f0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
21300 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
21310 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
21320 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
21330 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
21340 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
21350 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
21360 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21370 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
21380 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
21390 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
213a0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
213b0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
213c0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
213d0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
213e0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
213f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
21400 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
21410 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
21420 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
21430 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
21440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
21450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
21460 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
21470 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
21480 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
21490 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
214a0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
214b0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
214c0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
214d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
214e0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
214f0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
21500 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
21510 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
21520 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
21530 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
21540 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
21550 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
21560 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21570 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
21580 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
21590 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
215a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
215b0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
215c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
215d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
215e0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
215f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21600 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
21610 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
21620 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21630 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
21640 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
21650 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
21660 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
21670 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
21680 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
21690 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
216a0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
216b0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
216c0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
216d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
216e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
216f0 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
21700 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
21710 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
21720 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
21730 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
21740 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
21750 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
21760 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
21770 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
21780 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
21790 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
217a0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
217b0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
217c0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
217d0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
217e0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
217f0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
21800 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
21810 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
21820 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
21830 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
21840 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
21850 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
21860 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
21870 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
21880 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
21890 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
218a0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
218b0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
218c0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
218d0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
218e0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
218f0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
21900 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
21910 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
21920 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
21930 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
21940 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
21950 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
21960 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
21970 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
21980 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
21990 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
219a0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
219b0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
219c0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
219d0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
219e0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
219f0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
21a00 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
21a10 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
21a20 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
21a30 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
21a40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
21a50 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
21a60 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
21a70 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
21a80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
21a90 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
21aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21ab0 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
21ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
21ad0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
21ae0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
21af0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
21b00 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
21b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
21b20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
21b30 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
21b40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21b50 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
21b60 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
21b70 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
21b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21b90 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
21ba0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
21bb0 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
21bc0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
21bd0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
21be0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
21bf0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
21c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
21c10 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
21c20 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
21c30 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
21c40 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
21c50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21c60 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
21c70 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
21c80 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
21c90 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
21ca0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
21cb0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
21cc0 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
21cd0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21ce0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
21cf0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
21d00 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
21d10 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
21d20 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
21d30 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
21d40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21d50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21d60 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
21d70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21d80 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
21d90 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
21da0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21db0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
21dc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
21dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21de0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
21df0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21e00 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
21e10 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
21e20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21e30 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
21e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
21e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21e60 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
21e70 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
21e80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21e90 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
21ea0 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
21eb0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
21ec0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
21ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21ee0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
21ef0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21f00 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
21f10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
21f20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
21f30 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
21f40 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21f50 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
21f60 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
21f70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
21f80 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
21f90 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
21fa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
21fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21fc0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
21fd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
21fe0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
21ff0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
22000 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
22010 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
22020 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
22030 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
22040 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
22050 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
22060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22070 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
22080 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
22090 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
220a0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
220b0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
220c0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
220d0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
220e0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
220f0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
22100 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
22110 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
22120 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
22130 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
22140 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
22150 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
22160 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
22170 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
22180 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
22190 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
221a0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
221b0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
221c0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
221d0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
221e0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
221f0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22200 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
22210 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
22220 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
22230 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
22240 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22250 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
22260 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
22270 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22280 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
22290 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
222a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
222b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
222c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
222d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
222e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
222f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
22300 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
22310 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
22320 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
22330 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
22340 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
22350 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
22360 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
22370 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
22380 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22390 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
223a0 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
223b0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
223c0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
223d0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
223e0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
223f0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
22400 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
22410 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
22420 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
22430 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
22440 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
22450 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
22460 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
22470 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
22480 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
22490 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
224a0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
224b0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
224c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
224d0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
224e0 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
224f0 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
22500 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
22510 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
22520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
22530 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
22540 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
22550 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
22560 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
22570 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
22580 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
22590 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
225a0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
225b0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
225c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
225d0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
225e0 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
225f0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
22600 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
22610 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
22620 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
22630 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
22640 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
22650 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
22660 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
22670 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22680 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22690 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
226a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
226b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
226c0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
226d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
226e0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
226f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22700 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
22710 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
22720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
22730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22740 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
22750 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
22760 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
22770 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
22780 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
22790 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
227a0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
227b0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
227c0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
227d0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
227e0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
227f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
22800 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
22810 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
22820 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
22830 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
22840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
22850 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
22860 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
22870 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
22880 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
22890 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
228a0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
228b0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
228c0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
228d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
228e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
228f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
22900 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
22910 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
22920 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22930 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
22940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
22950 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
22960 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
22970 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22980 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
22990 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
229a0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
229b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
229c0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
229d0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
229e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
229f0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
22a00 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
22a10 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
22a20 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
22a30 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
22a40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
22a50 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
22a60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22a70 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
22a80 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
22a90 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
22aa0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
22ab0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
22ac0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
22ad0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
22ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22af0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
22b00 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
22b10 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
22b20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
22b30 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
22b40 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
22b50 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
22b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22b70 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
22b80 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
22b90 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
22ba0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
22bb0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
22bc0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
22bd0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
22be0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
22bf0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
22c00 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
22c10 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22c20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22c30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22c40 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
22c50 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
22c60 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
22c70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
22c80 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
22c90 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
22ca0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
22cb0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
22cc0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
22cd0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
22ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22cf0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
22d00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22d10 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
22d20 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
22d30 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
22d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22d50 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
22d60 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22d70 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
22d80 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
22d90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22da0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
22db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
22dc0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
22dd0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
22de0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
22df0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22e00 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
22e10 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
22e20 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
22e30 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
22e40 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
22e50 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
22e60 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
22e70 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
22e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
22e90 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
22ea0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22eb0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
22ec0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
22ed0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
22ee0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
22ef0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
22f00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22f10 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
22f20 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
22f30 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
22f40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
22f50 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
22f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22f70 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
22f80 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
22f90 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
22fa0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
22fb0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
22fc0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
22fd0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
22fe0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
22ff0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
23000 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
23010 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
23020 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
23030 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
23040 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
23050 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
23060 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
23070 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
23080 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
23090 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
230a0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
230b0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
230c0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
230d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
230e0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
230f0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
23100 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
23110 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
23120 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
23130 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
23140 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
23150 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
23160 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
23180 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23190 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
231a0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
231b0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
231c0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
231d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
231e0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
231f0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
23200 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
23210 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
23220 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
23230 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
23240 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
23250 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
23260 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
23270 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
23280 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
23290 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
232a0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
232b0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
232c0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
232d0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
232e0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
232f0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
23300 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
23310 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
23320 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
23330 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
23340 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
23350 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
23360 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
23370 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
23380 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
23390 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
233a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
233b0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
233c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
233d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
233e0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
233f0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
23400 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
23410 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
23420 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
23430 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
23440 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
23450 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
23460 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
23470 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
23480 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
23490 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
234a0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
234b0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
234c0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
234d0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
234e0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
234f0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
23500 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
23510 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
23520 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
23530 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
23540 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
23550 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
23560 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
23570 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
23580 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
23590 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
235a0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
235b0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
235c0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
235d0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
235e0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
235f0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
23600 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23610 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
23620 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
23630 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
23640 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
23650 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
23660 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
23670 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
23680 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
23690 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
236a0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
236b0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
236c0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
236d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
236e0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
236f0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
23700 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
23710 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
23720 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
23730 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
23740 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
23750 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
23760 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
23770 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
23780 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
23790 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
237a0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
237b0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
237c0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
237d0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
237e0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
237f0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
23800 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
23810 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
23820 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
23830 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
23840 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
23850 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
23860 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
23870 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
23880 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
23890 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
238a0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
238b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
238c0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
238d0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
238e0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
238f0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
23900 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
23910 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
23920 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
23930 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
23940 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
23950 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
23960 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
23970 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
23980 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
23990 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
239a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
239b0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
239c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
239d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
239e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
239f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
23a00 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
23a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23a20 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
23a30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23a60 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
23a70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
23a80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23a90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
23aa0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
23ab0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
23ac0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23ad0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
23ae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23af0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
23b00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23b10 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
23b20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23b30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23b50 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
23b60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
23b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
23b80 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
23b90 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
23ba0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
23bb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23bc0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
23bd0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
23be0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
23bf0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23c00 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
23c10 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
23c20 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
23c30 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
23c40 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
23c50 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
23c60 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
23c70 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
23c80 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
23c90 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
23ca0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
23cb0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
23cc0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
23cd0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23ce0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
23cf0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
23d00 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
23d10 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
23d20 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
23d30 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
23d40 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
23d50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
23d60 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
23d70 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
23d80 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
23d90 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
23da0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
23db0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
23dc0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
23dd0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
23de0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
23df0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
23e00 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
23e10 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
23e20 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
23e30 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
23e40 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
23e50 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
23e60 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
23e70 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
23e80 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
23e90 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
23ea0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
23eb0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
23ec0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
23ed0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
23ee0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
23ef0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
23f00 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
23f10 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
23f20 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
23f30 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
23f40 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
23f50 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
23f60 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
23f70 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
23f80 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
23f90 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
23fa0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
23fb0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
23fc0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
23fd0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
23fe0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
23ff0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
24000 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24010 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
24020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
24030 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
24040 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
24050 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
24060 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
24070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24080 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
24090 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
240a0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
240b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
240c0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
240d0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
240e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
240f0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
24100 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24110 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
24120 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
24130 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
24140 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
24150 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
24160 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
24170 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
24180 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
24190 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
241a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
241b0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
241c0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
241d0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
241e0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
241f0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
24200 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
24210 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
24220 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
24230 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
24240 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
24250 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
24260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24270 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
24280 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
24290 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
242a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
242b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
242c0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
242d0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
242e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
242f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
24300 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
24310 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
24320 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
24330 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
24340 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
24350 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
24360 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
24370 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
24380 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
24390 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
243a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
243b0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
243c0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
243d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
243e0 2a 2a 20 5e 57 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 2c 20 61 6e 79  " interface, any
24400 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
24410 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
24420 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
24430 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
24440 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
24450 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
24460 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
24470 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
24480 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
24490 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
244a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
244b0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
244c0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
244d0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
244e0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
244f0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
24500 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
24510 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
24520 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
24530 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
24540 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
24550 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
24560 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
24570 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
24580 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
24590 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
245a0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
245b0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
245c0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
245d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
245e0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
245f0 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
24600 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
24610 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
24620 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
24630 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
24640 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
24650 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
24660 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
24670 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
24680 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
24690 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
246a0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
246b0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
246c0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
246d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
246e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
246f0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
24700 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
24710 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
24720 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
24730 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
24740 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
24750 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
24760 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
24770 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
24780 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
24790 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
247a0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
247b0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
247c0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
247d0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
247e0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
247f0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
24800 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
24810 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
24820 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
24830 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
24840 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
24850 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
24860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
24870 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
24880 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
24890 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
248a0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
248b0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
248c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
248d0 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
248e0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
248f0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
24900 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
24910 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
24920 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
24930 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
24940 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
24950 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
24960 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
24970 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
24980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
24990 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
249a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
249b0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
249c0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
249d0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
249e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
249f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
24a00 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
24a10 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
24a20 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
24a30 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
24a40 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
24a50 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
24a60 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
24a70 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
24a80 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24a90 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
24aa0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
24ab0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24ac0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
24ad0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
24ae0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
24af0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
24b00 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
24b10 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
24b20 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
24b30 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
24b40 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
24b50 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
24b60 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
24b70 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
24b80 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
24b90 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
24ba0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
24bb0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
24bc0 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
24bd0 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
24be0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
24bf0 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
24c00 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
24c10 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
24c20 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
24c30 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
24c40 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
24c50 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
24c60 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
24c70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
24c80 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
24c90 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
24ca0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
24cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24cc0 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
24cd0 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
24ce0 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
24cf0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
24d00 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
24d10 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  r version 3.6.23
24d20 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
24d30 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
24d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24d50 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
24d60 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
24d70 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
24d80 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
24d90 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
24da0 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
24db0 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
24dc0 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
24dd0 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
24de0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
24df0 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
24e00 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
24e10 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
24e20 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
24e30 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
24e40 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
24e50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
24e60 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
24e70 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
24e80 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
24e90 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
24ea0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
24eb0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
24ec0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
24ed0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
24ee0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
24ef0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
24f00 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
24f10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
24f20 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
24f30 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
24f40 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
24f50 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
24f60 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
24f70 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
24f80 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
24f90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
24fa0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
24fb0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
24fc0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
24fd0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
24fe0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24ff0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
25000 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
25010 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
25020 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
25030 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
25040 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
25050 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
25060 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
25070 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
25080 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
25090 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
250a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
250b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
250c0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
250d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
250e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
250f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
25100 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
25110 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
25120 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
25130 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
25140 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
25150 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
25160 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
25170 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
25180 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
25190 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
251a0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
251b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
251c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
251d0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
251e0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
251f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
25200 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25210 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
25220 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
25230 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
25240 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
25250 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
25260 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
25270 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
25280 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
25290 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
252a0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
252b0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
252c0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
252d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
252e0 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
252f0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
25300 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
25310 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
25320 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
25330 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
25340 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
25350 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
25360 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
25370 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
25380 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
25390 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
253a0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
253b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
253c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
253d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
253e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
253f0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
25400 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
25410 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
25420 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
25430 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
25440 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
25450 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
25460 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25470 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
25480 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
25490 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
254a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
254b0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
254c0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
254d0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
254e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
254f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
25500 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
25510 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
25520 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
25530 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
25540 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
25550 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
25560 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
25570 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
25580 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
25590 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
255a0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
255b0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
255c0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
255d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
255e0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
255f0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
25600 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
25610 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
25620 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
25630 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
25640 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
25650 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
25660 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
25670 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
25680 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
25690 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
256a0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
256b0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
256c0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
256d0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
256e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
256f0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
25700 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
25710 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
25720 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
25730 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
25740 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
25750 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
25760 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
25770 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
25780 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
25790 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
257a0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
257b0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
257c0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
257d0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
257e0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
257f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25800 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
25810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25820 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
25830 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
25840 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
25850 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
25860 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
25870 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
25880 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
25890 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
258a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
258b0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
258c0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
258d0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
258e0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
258f0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
25900 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
25910 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
25920 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
25930 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
25940 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
25950 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
25960 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
25970 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
25980 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
25990 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
259a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
259b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
259c0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
259d0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
259e0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
259f0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
25a00 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
25a10 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
25a20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
25a30 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
25a40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25a50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
25a60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
25a70 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25a80 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
25a90 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
25aa0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
25ab0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25ac0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
25ad0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
25ae0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
25af0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
25b00 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
25b10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
25b20 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
25b30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
25b40 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
25b50 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
25b60 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
25b70 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
25b80 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
25b90 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
25ba0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
25bb0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
25bc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
25bd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25be0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
25bf0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
25c00 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
25c10 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
25c20 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
25c30 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
25c40 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
25c50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
25c60 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
25c70 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
25c80 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
25c90 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
25ca0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
25cb0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
25cc0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
25cd0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
25ce0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
25cf0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
25d00 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
25d10 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
25d20 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
25d30 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
25d40 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
25d50 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
25d60 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
25d70 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
25d80 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
25d90 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
25da0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
25db0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
25dc0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
25dd0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
25de0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
25df0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
25e00 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
25e10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
25e20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
25e30 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
25e40 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
25e50 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
25e60 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
25e70 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
25e80 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
25e90 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
25ea0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
25eb0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
25ec0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
25ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
25ee0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
25ef0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
25f00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
25f10 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
25f20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
25f30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
25f40 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
25f50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25f60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
25f70 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
25f80 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
25f90 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
25fa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25fb0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
25fc0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
25fd0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
25fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25ff0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
26000 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
26010 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
26020 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
26030 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
26040 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
26050 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26060 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
26070 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
26080 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
26090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
260a0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
260b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
260c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
260d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
260e0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
260f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
26100 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
26110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26120 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
26130 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
26140 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
26150 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
26160 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
26170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26180 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
26190 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
261a0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
261b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
261c0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
261d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
261e0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
261f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
26200 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
26210 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
26220 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
26230 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
26240 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
26250 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
26260 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
26270 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
26280 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
26290 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
262a0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
262b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
262c0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
262d0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
262e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
262f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26300 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
26310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26320 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
26330 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
26340 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
26350 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
26360 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
26370 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
26380 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
26390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
263a0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
263b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
263c0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
263d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
263e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
263f0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
26400 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
26410 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
26420 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by 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 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
26450 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
26460 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
26470 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
26480 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
26490 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
264a0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
264b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
264c0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
264d0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
264e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
264f0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
26500 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
26510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
26520 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
26530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26550 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
26560 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26570 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
26580 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
26590 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
265a0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
265b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
265c0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
265d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
265e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
265f0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
26600 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
26610 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
26620 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
26630 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
26640 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
26650 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
26660 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
26670 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
26680 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
26690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
266a0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
266b0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
266c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
266d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
266e0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
266f0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
26700 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
26710 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
26720 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
26730 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
26740 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
26750 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
26760 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
26770 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
26780 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
26790 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
267a0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
267b0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
267c0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
267d0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
267e0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
267f0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
26800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
26810 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
26820 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
26830 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
26840 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
26850 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
26860 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
26870 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
26880 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
26890 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
268a0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
268b0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
268c0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
268d0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
268e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
268f0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
26900 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
26910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
26920 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
26930 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
26940 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
26950 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
26960 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
26970 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
26980 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
26990 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
269a0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
269b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
269c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
269d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
269e0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
269f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
26a00 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
26a10 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
26a20 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
26a30 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26a40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
26a50 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
26a60 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
26a70 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
26a80 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
26a90 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
26aa0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
26ab0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
26ac0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
26ad0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
26ae0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
26af0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
26b00 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
26b10 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
26b20 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
26b30 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
26b40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26b50 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
26b60 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
26b70 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
26b80 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
26b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
26ba0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
26bb0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
26bc0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
26bd0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
26be0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
26bf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26c00 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
26c10 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
26c20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
26c30 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
26c40 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
26c50 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
26c60 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
26c70 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
26c80 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
26c90 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
26ca0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
26cb0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
26cc0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
26cd0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
26ce0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
26cf0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
26d00 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
26d10 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
26d20 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
26d30 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
26d40 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
26d50 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
26d60 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
26d70 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
26d80 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
26d90 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
26da0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
26db0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
26dc0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
26dd0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
26de0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
26df0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
26e00 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
26e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
26e20 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
26e30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
26e40 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
26e50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26e60 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
26e70 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
26e80 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
26e90 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
26ea0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
26eb0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
26ec0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
26ed0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
26ee0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
26ef0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
26f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26f10 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
26f20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
26f30 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
26f40 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
26f50 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
26f60 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
26f70 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
26f80 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
26f90 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
26fa0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
26fb0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
26fc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
26fd0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
26fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26ff0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
27000 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
27010 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
27020 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
27030 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
27040 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
27050 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
27060 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
27070 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
27080 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
27090 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
270a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
270b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
270c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
270d0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
270e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
270f0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
27100 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
27110 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
27120 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
27130 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
27140 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
27150 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
27160 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
27170 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27180 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
27190 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
271a0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
271b0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
271c0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
271d0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
271e0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
271f0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
27200 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
27210 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
27220 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
27230 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
27240 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
27250 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
27260 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
27270 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
27280 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
27290 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
272a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
272b0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
272c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
272d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
272e0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
272f0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
27300 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27310 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
27320 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
27330 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
27340 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
27350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27360 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
27370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27380 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
27390 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
273a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
273b0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
273c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
273d0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
273e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
273f0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
27400 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27410 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
27420 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
27430 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
27440 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
27450 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
27460 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
27470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27480 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
27490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
274a0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
274b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
274c0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
274d0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
274e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
274f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
27500 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
27510 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
27520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27530 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
27540 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
27550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27560 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
27570 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
27580 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
27590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
275a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
275b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
275c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
275d0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
275e0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
275f0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
27600 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
27610 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
27620 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
27630 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
27640 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
27650 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
27660 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
27670 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
27680 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
27690 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
276a0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
276b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
276c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
276d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
276e0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
276f0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
27700 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
27710 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
27720 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
27730 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
27740 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
27750 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
27760 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
27770 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
27780 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
27790 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
277a0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
277b0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
277c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
277d0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
277e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
277f0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27800 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
27810 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
27820 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
27830 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
27840 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
27850 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
27860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27870 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
27880 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
27890 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
278a0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
278b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
278c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
278d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
278e0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
278f0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
27900 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
27910 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
27920 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
27930 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27940 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
27950 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
27960 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
27970 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
27980 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
27990 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
279a0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
279b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
279c0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
279d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
279e0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
279f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27a10 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
27a20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27a30 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
27a40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27a50 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
27a60 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a80 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
27a90 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
27aa0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
27ab0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27ac0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
27ad0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
27ae0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27af0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
27b00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
27b10 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
27b20 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
27b30 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
27b40 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65   or.** or if the
27b50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
27b60 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
27b70 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
27b80 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
27b90 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
27ba0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
27bb0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
27bc0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
27bd0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
27be0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27bf0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
27c00 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
27c10 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
27c20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
27c30 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
27c40 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
27c50 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
27c60 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
27c70 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
27c80 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
27c90 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
27ca0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
27cb0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
27cc0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
27cd0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
27ce0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
27cf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27d00 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
27d10 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
27d20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27d30 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
27d40 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
27d50 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
27d60 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
27d70 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
27d80 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
27d90 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
27da0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
27db0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
27dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
27dd0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
27de0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
27df0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27e00 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
27e10 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
27e20 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
27e30 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
27e40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27e50 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
27e60 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
27e70 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
27e80 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
27e90 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
27ea0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
27eb0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
27ec0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
27ed0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
27ee0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
27ef0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
27f00 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
27f10 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
27f20 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
27f30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
27f40 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
27f50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
27f70 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
27f80 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27f90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27fa0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
27fb0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
27fc0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
27fd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27fe0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
27ff0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
28000 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
28010 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
28020 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
28030 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
28040 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
28050 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
28060 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
28070 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
28080 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
28090 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
280a0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
280b0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
280c0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
280d0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
280e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
280f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
28100 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
28110 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28120 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
28130 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
28140 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
28150 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
28160 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
28170 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28180 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
28190 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
281a0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
281b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
281c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
281d0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
281e0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
281f0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
28200 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
28210 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
28220 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
28230 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
28240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
28250 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28260 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28270 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
28280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28290 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
282a0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
282b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
282c0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
282d0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
282e0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
282f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
28300 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
28310 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
28320 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
28330 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
28340 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
28350 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
28360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
28370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28380 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
28390 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
283a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
283b0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
283c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
283d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
283e0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
283f0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
28400 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
28410 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28420 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
28430 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
28440 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28450 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
28460 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28470 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
28480 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
28490 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
284a0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
284b0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
284c0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
284d0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
284e0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
284f0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
28500 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
28510 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
28520 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
28530 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
28540 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
28550 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
28560 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
28570 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
28580 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
28590 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
285a0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
285b0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
285c0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
285d0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
285e0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
285f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28600 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
28610 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
28620 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
28630 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28640 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
28650 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
28660 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
28670 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
28680 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
28690 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
286a0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
286b0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
286c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
286d0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
286e0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
286f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28700 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
28710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
28720 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
28730 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
28740 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
28750 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
28760 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
28770 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
28780 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
28790 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
287a0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
287b0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
287c0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
287d0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
287e0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
287f0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
28800 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
28810 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
28820 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
28830 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
28840 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
28850 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
28860 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
28870 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
28880 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
28890 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
288a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
288b0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
288c0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
288d0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
288e0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
288f0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
28900 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
28910 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
28920 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
28930 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28940 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
28950 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
28960 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
28970 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
28980 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
28990 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
289a0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
289b0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
289c0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
289d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
289e0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
289f0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
28a00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28a10 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
28a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
28a30 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
28a40 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
28a50 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
28a60 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
28a70 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
28a80 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
28a90 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
28aa0 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
28ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
28ad0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
28ae0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
28af0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
28b00 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
28b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28b20 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
28b30 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
28b40 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
28b50 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
28b60 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
28b70 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
28b80 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28b90 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
28ba0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28bb0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
28bc0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
28bd0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
28be0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
28bf0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
28c00 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
28c10 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
28c20 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
28c30 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
28c40 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
28c50 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
28c60 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
28c70 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
28c80 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
28c90 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
28ca0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
28cb0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
28cc0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
28cd0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
28ce0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
28cf0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
28d00 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
28d10 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
28d20 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
28d30 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
28d40 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
28d50 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
28d60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28d70 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
28d80 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
28d90 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
28da0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
28db0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
28dc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
28dd0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
28de0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
28df0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
28e00 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
28e10 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
28e20 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
28e30 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
28e40 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
28e50 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
28e60 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
28e70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28e80 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28e90 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
28ea0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
28eb0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
28ec0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
28ed0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
28ee0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
28ef0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
28f00 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28f10 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
28f20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28f30 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
28f40 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
28f50 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
28f60 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
28f70 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
28f80 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
28f90 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
28fa0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
28fb0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
28fc0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
28fd0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
28fe0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
28ff0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
29000 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29010 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
29020 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
29030 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
29040 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
29050 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
29060 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
29070 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
29080 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
29090 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
290a0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
290b0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
290c0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
290d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
290e0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
290f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
29100 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
29110 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
29120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29130 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
29140 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
29150 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
29160 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
29170 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
29180 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
29190 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
291a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
291b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
291c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
291d0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
291e0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
291f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29210 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
29220 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
29230 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
29240 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
29250 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
29260 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
29270 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
29280 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
29290 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
292a0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
292b0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
292c0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
292d0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
292e0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
292f0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
29300 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
29310 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
29320 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
29330 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
29340 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
29350 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
29360 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
29370 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
29380 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
29390 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
293a0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
293b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
293c0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
293d0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
293e0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
293f0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
29400 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
29410 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
29420 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
29430 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
29440 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
29450 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
29460 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
29470 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
29480 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
29490 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
294a0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
294b0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
294c0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
294d0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
294e0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
294f0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
29500 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
29510 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
29520 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
29530 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
29540 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
29550 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29560 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
29570 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
29580 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29590 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
295a0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
295b0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
295c0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
295d0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
295e0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
295f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29600 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
29610 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
29620 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
29630 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
29640 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
29650 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
29660 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29670 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
29680 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
29690 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
296a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
296b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
296c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
296d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
296e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
296f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
29700 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
29710 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
29720 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
29730 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
29740 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
29750 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
29760 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29770 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29780 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29790 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
297a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
297b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
297c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
297d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
297e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
297f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29800 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29810 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
29820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29830 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
29840 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
29850 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
29860 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
29870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29880 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
29890 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
298a0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
298b0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
298c0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
298d0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
298e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
298f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
29900 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
29910 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
29920 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
29930 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
29940 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
29950 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
29960 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29970 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
29980 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
29990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
299a0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
299b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
299c0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
299d0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
299e0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
299f0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
29a00 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
29a10 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
29a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
29a30 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
29a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
29a50 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
29a60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
29a70 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
29a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
29a90 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
29aa0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
29ab0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
29ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
29ad0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
29ae0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
29af0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
29b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
29b10 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
29b20 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
29b30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29b40 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
29b50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
29b60 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
29b70 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
29b80 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
29b90 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
29ba0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
29bb0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
29bc0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
29bd0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
29be0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
29bf0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
29c00 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
29c10 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
29c20 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
29c30 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
29c40 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
29c50 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
29c60 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
29c70 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
29c80 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
29c90 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
29ca0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
29cb0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
29cc0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
29cd0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
29ce0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
29cf0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
29d00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29d10 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
29d20 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
29d30 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
29d40 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
29d50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
29d60 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
29d70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
29d80 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
29d90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
29da0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
29db0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
29dd0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
29de0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
29df0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
29e00 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
29e10 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
29e20 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29e30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
29e40 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
29e50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
29e60 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
29e70 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
29e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29e90 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
29ea0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
29eb0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
29ec0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
29ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
29ee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
29ef0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
29f00 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
29f10 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
29f20 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
29f30 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
29f40 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
29f50 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
29f60 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
29f70 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
29f80 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
29f90 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
29fa0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
29fb0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
29fc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
29fd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
29fe0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29ff0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
2a000 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
2a010 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2a020 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2a030 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
2a040 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2a050 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
2a060 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2a070 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2a080 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a090 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2a0a0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2a0b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a0c0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2a0d0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2a0e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a0f0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2a100 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2a110 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2a120 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2a130 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2a140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2a150 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2a160 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2a170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a180 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2a190 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2a1a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2a1b0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2a1c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2a1d0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2a1e0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2a1f0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
2a200 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2a210 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
2a220 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2a230 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2a240 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
2a250 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
2a260 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
2a270 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
2a280 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2a290 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
2a2a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
2a2b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
2a2c0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
2a2d0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
2a2e0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
2a2f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2a300 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2a310 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2a320 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2a330 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2a340 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2a350 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
2a360 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2a370 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2a380 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2a390 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2a3a0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2a3b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2a3c0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2a3d0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2a3e0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2a3f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
2a400 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2a410 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2a420 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2a430 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2a440 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2a450 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2a460 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2a470 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2a480 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2a490 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2a4a0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2a4b0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2a4c0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2a4d0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2a4e0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2a4f0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2a500 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
2a510 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2a520 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2a530 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2a540 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2a550 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
2a560 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
2a570 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
2a580 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
2a590 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2a5a0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2a5b0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2a5c0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
2a5d0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
2a5e0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
2a5f0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
2a600 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
2a610 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2a620 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
2a630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a640 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
2a650 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a660 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
2a670 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
2a680 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2a690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2a6a0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
2a6b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2a6c0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
2a6d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2a6e0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2a6f0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
2a700 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a710 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2a720 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2a730 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2a740 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2a750 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2a760 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a770 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2a780 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2a790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2a7a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a7b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2a7c0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2a7d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2a7e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2a7f0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
2a800 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
2a810 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2a820 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2a830 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2a840 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
2a850 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
2a860 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2a870 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
2a880 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2a890 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a8a0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2a8b0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
2a8c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2a8d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2a8e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
2a8f0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2a900 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2a910 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2a920 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2a930 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a940 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
2a950 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a960 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a970 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
2a980 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2a990 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2a9a0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
2a9b0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
2a9c0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
2a9d0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
2a9e0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
2a9f0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
2aa00 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
2aa10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
2aa20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
2aa30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
2aa40 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
2aa50 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
2aa60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
2aa70 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
2aa80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2aa90 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
2aaa0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
2aab0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2aac0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
2aad0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
2aae0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
2aaf0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
2ab00 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
2ab10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
2ab20 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
2ab30 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
2ab40 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
2ab50 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2ab60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ab70 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
2ab80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2ab90 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
2aba0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
2abb0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
2abc0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
2abd0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
2abe0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
2abf0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
2ac00 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
2ac10 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
2ac20 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
2ac30 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
2ac40 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
2ac50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2ac60 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
2ac70 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
2ac80 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
2ac90 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
2aca0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
2acb0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
2acc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2acd0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
2ace0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
2acf0 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
2ad00 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
2ad10 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
2ad20 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ad30 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
2ad40 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
2ad50 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
2ad60 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
2ad70 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2ad80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ad90 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2ada0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
2adb0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
2adc0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
2add0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
2ade0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
2adf0 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
2ae00 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
2ae10 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
2ae20 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
2ae30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2ae40 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
2ae50 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
2ae60 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
2ae70 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
2ae80 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
2ae90 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
2aea0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
2aeb0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2aec0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2aed0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
2aee0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
2aef0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2af00 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
2af10 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
2af20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
2af30 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
2af40 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2af50 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
2af60 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2af70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2af80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2af90 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2afa0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
2afb0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2afc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
2afd0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
2afe0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2aff0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
2b000 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
2b010 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
2b020 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
2b030 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
2b040 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
2b050 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
2b060 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
2b070 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
2b080 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2b090 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2b0a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2b0b0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2b0c0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
2b0d0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2b0e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2b0f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2b100 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2b110 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b120 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2b130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2b140 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2b150 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2b160 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2b170 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2b180 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2b190 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2b1a0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2b1b0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2b1c0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2b1d0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2b1e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b1f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2b200 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2b210 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2b220 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2b230 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2b240 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2b250 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2b260 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2b270 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2b280 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2b290 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2b2a0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2b2b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b2c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2b2d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2b2e0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
2b2f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2b300 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2b310 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2b320 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
2b330 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2b340 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2b350 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2b360 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b370 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2b380 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2b390 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b3a0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2b3b0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2b3c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2b3d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b3e0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2b3f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b400 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2b410 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2b420 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2b430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b440 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b450 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2b460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2b470 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2b480 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2b490 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
2b4a0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
2b4b0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
2b4c0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
2b4d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
2b4e0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
2b4f0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
2b500 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
2b510 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2b520 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2b530 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2b540 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2b550 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2b560 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2b570 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2b580 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2b590 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2b5a0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2b5b0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2b5c0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
2b5d0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
2b5e0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
2b5f0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
2b600 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
2b610 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
2b620 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
2b630 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
2b640 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
2b650 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2b660 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
2b670 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2b680 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
2b690 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
2b6a0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
2b6b0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
2b6c0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
2b6d0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
2b6e0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
2b6f0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
2b700 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
2b710 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2b720 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
2b730 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
2b740 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
2b750 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
2b760 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
2b770 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
2b780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b790 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
2b7a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b7b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2b7c0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
2b7d0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
2b7e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2b7f0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
2b800 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
2b810 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
2b820 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b830 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b840 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
2b850 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
2b860 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
2b870 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2b880 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
2b890 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
2b8a0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
2b8b0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2b8c0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
2b8d0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
2b8e0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
2b8f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
2b900 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
2b910 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2b920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b930 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2b940 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
2b950 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
2b960 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
2b970 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
2b980 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
2b990 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2b9a0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2b9b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b9c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2b9d0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2b9e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2b9f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2ba00 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2ba10 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2ba20 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2ba30 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
2ba40 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
2ba50 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2ba60 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2ba70 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
2ba80 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
2ba90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2baa0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
2bab0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
2bac0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
2bad0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
2bae0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
2baf0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
2bb00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2bb10 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
2bb20 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
2bb30 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
2bb40 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
2bb50 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
2bb60 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
2bb70 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
2bb80 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
2bb90 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
2bba0 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
2bbb0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
2bbc0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
2bbd0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
2bbe0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
2bbf0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
2bc00 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
2bc10 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2bc20 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
2bc30 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
2bc40 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
2bc50 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
2bc60 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
2bc70 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
2bc80 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
2bc90 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
2bca0 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
2bcb0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2bcc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2bcd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2bce0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2bcf0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bd00 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2bd10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2bd20 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2bd30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2bd40 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2bd50 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2bd60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bd70 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2bd80 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2bd90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bda0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2bdb0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2bdc0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2bdd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
2bde0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
2bdf0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
2be00 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
2be10 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
2be20 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
2be30 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2be40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2be50 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
2be60 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
2be70 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
2be80 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
2be90 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2bea0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
2beb0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
2bec0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
2bed0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
2bee0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
2bef0 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
2bf00 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2bf10 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2bf20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2bf30 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2bf40 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2bf50 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2bf60 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2bf70 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2bf80 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2bf90 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2bfa0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2bfb0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2bfc0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2bfd0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2bfe0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2bff0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2c000 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2c010 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2c020 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2c030 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2c040 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2c050 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2c060 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2c070 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2c080 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2c090 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2c0a0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2c0b0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2c0c0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2c0d0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
2c0e0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
2c0f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c100 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2c110 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2c120 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2c130 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2c140 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2c150 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2c160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2c170 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2c180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2c190 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2c1a0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2c1b0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2c1c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2c1d0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2c1e0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
2c1f0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2c200 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
2c210 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
2c220 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2c230 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2c240 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2c250 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2c260 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
2c270 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
2c280 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2c290 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2c2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c2b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2c2c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2c2d0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2c2e0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2c2f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c300 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
2c310 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
2c320 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
2c330 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
2c340 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
2c350 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
2c360 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
2c370 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
2c380 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2c390 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c3a0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
2c3b0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
2c3c0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2c3d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c3e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2c3f0 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
2c400 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
2c410 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
2c420 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
2c430 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
2c440 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
2c450 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2c460 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c470 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
2c480 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2c490 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2c4a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c4b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c4c0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
2c4d0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
2c4e0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
2c4f0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2c500 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2c510 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2c520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c530 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2c540 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2c550 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2c560 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2c570 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2c580 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
2c590 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2c5a0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2c5b0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2c5c0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2c5d0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2c5e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c5f0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2c600 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2c610 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
2c620 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
2c630 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2c640 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
2c650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2c660 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
2c670 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
2c680 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
2c690 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2c6a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
2c6b0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
2c6c0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
2c6d0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
2c6e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2c6f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c700 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2c710 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2c720 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
2c730 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2c740 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
2c750 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
2c760 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
2c770 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2c780 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2c790 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2c7a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2c7b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
2c7c0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2c7d0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2c7e0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
2c7f0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2c800 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
2c810 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2c820 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
2c830 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2c840 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2c850 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2c860 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2c870 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c880 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2c890 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
2c8a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2c8b0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2c8c0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2c8d0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2c8e0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2c8f0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2c900 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
2c910 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
2c920 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
2c930 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2c940 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c950 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2c960 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
2c970 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
2c980 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2c990 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
2c9a0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
2c9b0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
2c9c0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
2c9d0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
2c9e0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
2c9f0 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
2ca00 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2ca10 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2ca20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2ca30 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
2ca40 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
2ca50 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
2ca60 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
2ca70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
2ca80 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
2ca90 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2caa0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2cab0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2cac0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
2cad0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
2cae0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
2caf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cb00 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
2cb10 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2cb20 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2cb30 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
2cb40 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2cb50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2cb60 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
2cb70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2cb80 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2cb90 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2cba0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2cbb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2cbc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cbd0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2cbe0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2cbf0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2cc00 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2cc10 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
2cc20 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2cc30 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
2cc40 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2cc50 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2cc60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cc70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2cc80 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
2cc90 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2cca0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2ccb0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2ccc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ccd0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
2cce0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ccf0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2cd00 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2cd10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2cd20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
2cd30 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2cd40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cd50 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
2cd60 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
2cd70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cd80 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2cd90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cda0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2cdb0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2cdc0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2cdd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2cde0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cdf0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2ce00 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2ce10 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2ce20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2ce30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2ce40 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2ce50 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2ce60 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2ce70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2ce80 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
2ce90 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
2cea0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
2ceb0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
2cec0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2ced0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2cee0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2cef0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
2cf00 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2cf10 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2cf20 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2cf30 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
2cf40 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
2cf50 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
2cf60 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
2cf70 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
2cf80 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2cf90 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2cfa0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
2cfb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2cfc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cfd0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2cfe0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
2cff0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
2d000 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2d010 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
2d020 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
2d030 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
2d040 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
2d050 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
2d060 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
2d070 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
2d080 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2d090 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2d0a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d0b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2d0c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2d0d0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
2d0e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
2d0f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
2d100 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
2d110 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
2d120 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
2d130 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2d140 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2d150 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2d160 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
2d170 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2d180 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2d190 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2d1a0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
2d1b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
2d1c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2d1d0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2d1e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2d1f0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
2d200 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
2d210 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
2d220 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
2d230 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
2d240 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
2d250 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d260 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
2d270 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2d280 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
2d290 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
2d2a0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2d2b0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2d2c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2d2d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2d2e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2d2f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2d300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d310 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2d320 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2d330 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2d340 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2d350 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2d360 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2d370 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2d380 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2d390 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2d3a0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2d3b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d3c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2d3d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2d3e0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
2d3f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d400 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2d410 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
2d420 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
2d430 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d440 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
2d450 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
2d460 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
2d470 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2d480 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2d490 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
2d4a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d4b0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
2d4c0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
2d4d0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
2d4e0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2d4f0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
2d500 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
2d510 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
2d520 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
2d530 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
2d540 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
2d550 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d560 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2d570 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2d580 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2d590 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d5a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2d5b0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2d5c0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2d5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d5e0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2d5f0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2d600 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2d610 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2d620 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2d630 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2d640 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
2d650 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
2d660 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
2d670 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2d680 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
2d690 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
2d6a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
2d6b0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
2d6c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2d6d0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2d6e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2d6f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d700 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d710 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2d720 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d730 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
2d740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d750 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
2d760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d770 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2d780 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2d790 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2d7a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d7b0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
2d7c0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d7d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2d7e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d7f0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
2d800 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2d810 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d820 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
2d830 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d840 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d850 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
2d860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d870 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d880 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
2d890 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d8a0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d8b0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2d8c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d8d0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2d8e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d8f0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
2d900 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2d910 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d920 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
2d930 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d940 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
2d950 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d960 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d970 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d980 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d990 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2d9a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d9b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d9c0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2d9d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d9e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2d9f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2da00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2da10 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
2da20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2da30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2da40 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2da50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2da60 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
2da70 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2da80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
2da90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2daa0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2dab0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2dac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dad0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
2dae0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
2daf0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
2db00 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
2db10 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
2db20 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
2db30 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
2db40 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2db50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
2db60 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2db70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
2db80 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2db90 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2dba0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2dbb0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2dbc0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2dbd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2dbe0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2dbf0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2dc00 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
2dc10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2dc20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2dc30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2dc40 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
2dc50 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
2dc60 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
2dc70 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
2dc80 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
2dc90 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
2dca0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
2dcb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
2dcc0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
2dcd0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
2dce0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2dcf0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
2dd00 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2dd10 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
2dd20 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
2dd30 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2dd40 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
2dd50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2dd60 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
2dd70 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2dd80 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
2dd90 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
2dda0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
2ddb0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
2ddc0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
2ddd0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
2dde0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2ddf0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
2de00 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
2de10 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
2de20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2de30 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
2de40 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
2de50 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
2de60 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
2de70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2de80 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2de90 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
2dea0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
2deb0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
2dec0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
2ded0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
2dee0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
2def0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2df00 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
2df10 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2df20 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
2df30 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
2df40 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2df50 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
2df60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2df70 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2df80 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2df90 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
2dfa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2dfb0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2dfc0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
2dfd0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
2dfe0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
2dff0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2e000 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2e010 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
2e020 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
2e030 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
2e040 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
2e050 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
2e060 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
2e070 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2e080 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
2e090 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
2e0a0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
2e0b0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
2e0c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2e0d0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
2e0e0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
2e0f0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
2e100 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
2e110 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
2e120 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
2e130 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
2e140 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
2e150 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
2e160 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
2e170 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e180 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
2e190 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
2e1a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2e1b0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
2e1c0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
2e1d0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2e1e0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
2e1f0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
2e200 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
2e210 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
2e220 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
2e230 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
2e240 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
2e250 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
2e260 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2e270 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
2e280 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
2e290 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
2e2a0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
2e2b0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
2e2c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
2e2d0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
2e2e0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
2e2f0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
2e300 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
2e310 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
2e320 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
2e330 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
2e340 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
2e350 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
2e360 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
2e370 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
2e380 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
2e390 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
2e3a0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
2e3b0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
2e3c0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
2e3d0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2e3e0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
2e3f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
2e400 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
2e410 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
2e420 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
2e430 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
2e440 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
2e450 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
2e460 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
2e470 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
2e480 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
2e490 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
2e4a0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
2e4b0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
2e4c0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
2e4d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e4e0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
2e4f0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
2e500 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
2e510 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2e520 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
2e530 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
2e540 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
2e550 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
2e560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
2e580 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e590 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
2e5a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e5b0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
2e5c0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
2e5d0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
2e5e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2e5f0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
2e600 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
2e610 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
2e620 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
2e630 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
2e640 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
2e650 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2e660 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
2e670 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
2e680 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2e690 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2e6a0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
2e6b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2e6c0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
2e6d0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2e6e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
2e6f0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
2e700 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
2e710 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
2e720 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e730 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
2e740 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
2e750 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2e760 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
2e770 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e780 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
2e790 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
2e7a0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2e7b0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
2e7c0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
2e7d0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
2e7e0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2e7f0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
2e800 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
2e810 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
2e820 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
2e830 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
2e840 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
2e850 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
2e860 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
2e870 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
2e880 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
2e890 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
2e8a0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
2e8b0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
2e8c0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
2e8d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
2e8e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2e8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2e900 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2e910 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2e920 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2e930 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2e940 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2e950 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e960 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2e970 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2e980 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2e990 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2e9a0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2e9b0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2e9c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
2e9d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e9e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
2e9f0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2ea00 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2ea10 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2ea20 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
2ea30 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2ea40 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2ea50 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2ea60 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2ea70 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2ea80 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2ea90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2eaa0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2eab0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
2eac0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
2ead0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
2eae0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
2eaf0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2eb00 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2eb10 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2eb20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eb30 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
2eb40 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
2eb50 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
2eb60 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
2eb70 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
2eb80 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
2eb90 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
2eba0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
2ebb0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
2ebc0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
2ebd0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
2ebe0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2ebf0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
2ec00 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2ec10 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
2ec20 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2ec30 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
2ec40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
2ec50 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
2ec60 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
2ec70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ec80 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
2ec90 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
2eca0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
2ecb0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
2ecc0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2ecd0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
2ece0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
2ecf0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
2ed00 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2ed10 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
2ed20 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
2ed30 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
2ed40 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
2ed50 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
2ed60 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
2ed70 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
2ed80 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
2ed90 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
2eda0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2edb0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
2edc0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2edd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ede0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2edf0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2ee00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2ee10 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ee20 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2ee30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ee40 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2ee50 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2ee60 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2ee70 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2ee80 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
2ee90 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2eea0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2eeb0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2eec0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2eed0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
2eee0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
2eef0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2ef00 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2ef10 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
2ef20 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
2ef30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ef40 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2ef50 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
2ef60 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2ef70 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
2ef80 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2ef90 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
2efa0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
2efb0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
2efc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2efd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
2efe0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eff0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
2f000 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2f010 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2f020 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
2f030 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f040 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2f050 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2f060 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2f070 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2f080 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2f090 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2f0a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f0b0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2f0c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2f0d0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2f0e0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2f0f0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2f100 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
2f110 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2f120 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2f130 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2f140 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2f150 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2f160 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2f170 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2f180 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2f190 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2f1a0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2f1b0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2f1c0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2f1d0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2f1e0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2f1f0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2f200 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2f210 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2f220 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2f230 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2f240 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2f250 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2f260 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2f270 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2f280 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2f290 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2f2a0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2f2b0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2f2c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2f2d0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2f2e0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2f2f0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2f300 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2f310 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2f320 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2f330 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2f340 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2f350 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2f360 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2f370 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2f380 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2f390 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2f3a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f3b0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2f3c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2f3d0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2f3e0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2f3f0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2f400 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2f410 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2f420 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2f430 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2f440 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2f450 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2f460 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2f470 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2f480 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2f490 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2f4a0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2f4b0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2f4c0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2f4d0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2f4e0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2f4f0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2f500 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2f510 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2f520 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2f530 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2f540 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2f550 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2f560 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2f570 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2f580 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2f590 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2f5a0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2f5b0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2f5c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f5d0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2f5e0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2f5f0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f600 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2f610 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2f620 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2f630 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2f640 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2f650 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2f660 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2f670 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2f680 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2f690 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2f6a0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2f6b0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2f6c0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2f6d0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2f6e0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2f6f0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2f700 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2f710 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2f720 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
2f730 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2f740 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2f750 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2f760 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2f770 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2f780 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2f790 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2f7a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f7b0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2f7c0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2f7d0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2f7e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2f7f0 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
2f800 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
2f810 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
2f820 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
2f830 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
2f840 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
2f850 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
2f860 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f870 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
2f880 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
2f890 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
2f8a0 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
2f8b0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
2f8c0 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
2f8d0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2f8e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f8f0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2f900 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2f910 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2f920 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
2f930 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2f940 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2f950 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2f960 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2f970 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2f980 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2f990 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2f9a0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2f9b0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
2f9c0 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
2f9d0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
2f9e0 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
2f9f0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2fa00 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
2fa10 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2fa20 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2fa30 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2fa40 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2fa50 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2fa60 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2fa70 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2fa80 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2fa90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2faa0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2fab0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2fac0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2fad0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2fae0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2faf0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2fb00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2fb10 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2fb20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2fb30 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2fb40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2fb50 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2fb60 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2fb70 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2fb80 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2fb90 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2fba0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2fbb0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2fbc0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2fbd0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2fbe0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2fbf0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2fc00 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2fc10 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2fc20 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2fc30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
2fc40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fc50 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2fc60 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2fc70 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2fc80 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2fc90 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2fca0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2fcb0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
2fcc0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
2fcd0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fce0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
2fcf0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
2fd00 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
2fd10 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
2fd20 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
2fd30 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
2fd40 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
2fd50 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
2fd60 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
2fd70 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
2fd80 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
2fd90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2fda0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
2fdb0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
2fdc0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
2fdd0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
2fde0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
2fdf0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
2fe00 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2fe10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2fe20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2fe30 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
2fe40 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
2fe50 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fe60 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
2fe70 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
2fe80 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2fe90 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2fea0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2feb0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
2fec0 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
2fed0 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
2fee0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2fef0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
2ff00 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2ff10 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2ff20 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2ff30 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2ff40 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2ff50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ff60 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2ff70 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2ff80 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2ff90 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
2ffa0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2ffb0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
2ffc0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2ffd0 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2ffe0 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2fff0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
30000 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
30010 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
30020 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
30030 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
30040 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
30050 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
30060 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
30070 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
30080 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
30090 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
300a0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
300b0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
300c0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
300d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
300e0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
300f0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
30100 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
30110 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
30120 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
30130 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
30140 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
30150 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
30160 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
30170 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
30180 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
30190 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
301a0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
301b0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
301c0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
301d0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
301e0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
301f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30200 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
30210 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
30220 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
30230 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
30240 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
30250 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
30260 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
30270 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
30280 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
30290 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
302a0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
302b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
302c0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
302d0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
302e0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
302f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30300 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
30310 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
30320 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
30330 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
30340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
30350 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
30360 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
30370 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
30380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30390 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
303a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
303b0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
303c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
303d0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
303e0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
303f0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
30400 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
30410 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
30420 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
30430 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
30440 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
30450 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30460 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
30470 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
30480 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
30490 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
304a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
304b0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
304c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
304d0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
304e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
304f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30500 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
30510 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
30520 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
30530 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30540 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
30550 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
30560 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
30570 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
30580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30590 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
305a0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
305b0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
305c0 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
305d0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
305e0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
305f0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
30600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30610 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
30620 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
30630 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
30640 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
30650 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
30660 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30670 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
30680 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
30690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
306a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
306b0 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
306c0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
306d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
306e0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
306f0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
30700 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
30710 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
30720 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
30730 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30740 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
30750 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
30760 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
30770 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
30780 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
30790 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
307a0 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
307b0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
307c0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
307d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
307e0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
307f0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
30800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30810 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
30820 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
30830 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
30840 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
30850 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
30860 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
30870 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
30880 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
30890 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
308a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
308b0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
308c0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
308d0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
308e0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
308f0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
30900 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30910 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
30920 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
30930 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
30940 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
30950 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
30960 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
30970 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
30980 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
30990 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
309a0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
309b0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
309c0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
309d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
309e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
309f0 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
30a00 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
30a10 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
30a20 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
30a30 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
30a40 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
30a50 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
30a60 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
30a70 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
30a80 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
30a90 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
30aa0 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
30ab0 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
30ac0 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
30ad0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
30ae0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
30af0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
30b00 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
30b10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30b20 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
30b30 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
30b40 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
30b50 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
30b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30b70 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
30b80 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
30b90 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
30ba0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
30bb0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
30bc0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
30bd0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
30be0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
30bf0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
30c00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
30c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30c20 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
30c30 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
30c40 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
30c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30c60 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
30c70 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
30c80 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
30c90 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
30ca0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
30cb0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
30cc0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
30cd0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
30ce0 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
30cf0 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
30d00 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
30d10 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
30d20 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
30d30 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
30d40 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
30d50 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
30d60 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
30d70 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
30d80 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
30d90 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
30da0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
30db0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
30dc0 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
30dd0 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
30de0 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
30df0 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
30e00 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
30e10 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
30e20 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
30e30 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
30e40 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
30e50 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
30e60 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
30e70 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
30e80 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
30e90 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
30ea0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
30eb0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
30ec0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
30ed0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
30ee0 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
30ef0 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
30f00 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
30f10 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
30f20 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
30f30 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
30f40 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30f50 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
30f60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30f70 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
30f80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30f90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
30fa0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
30fb0 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
30fc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
30fd0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
30fe0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
30ff0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
31000 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
31010 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
31020 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
31030 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
31040 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
31050 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
31060 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
31070 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
31080 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
31090 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
310a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
310b0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
310c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
310d0 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
310e0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
310f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
31100 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
31110 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
31120 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
31130 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
31140 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
31150 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
31160 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
31170 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
31180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31190 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
311a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
311b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
311c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
311d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
311e0 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
311f0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
31200 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
31210 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
31220 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
31230 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
31240 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
31250 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
31260 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
31270 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
31280 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
31290 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
312a0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
312b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
312c0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
312d0 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
312e0 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
312f0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
31300 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
31310 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
31320 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
31330 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
31340 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
31350 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
31360 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
31370 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
31380 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
31390 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
313a0 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
313b0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
313c0 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
313d0 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
313e0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
313f0 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
31400 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
31410 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
31420 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
31430 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
31440 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
31450 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
31460 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
31470 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
31480 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
31490 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
314a0 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
314b0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
314c0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
314d0 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
314e0 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
314f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
31500 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
31510 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
31520 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
31530 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
31540 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
31550 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
31560 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
31570 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
31580 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
31590 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
315a0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
315b0 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
315c0 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
315d0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
315e0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
315f0 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
31600 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
31610 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
31620 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
31630 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
31640 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
31650 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
31660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31670 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
31680 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
31690 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
316a0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
316b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
316c0 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
316d0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
316e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
316f0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
31700 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
31710 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
31720 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
31730 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
31740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31750 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31760 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
31770 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
31780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31790 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
317a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
317b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
317c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
317d0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
317e0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
317f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
31800 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
31810 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
31820 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
31830 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31840 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
31850 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
31860 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
31870 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
31880 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
31890 5f 68 6f 6f 6b 28 29 5d 2c 20 5b 73 71 6c 69 74  _hook()], [sqlit
318a0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
318b0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  ()],.** and [sql
318c0 69 74 65 33 5f 70 72 65 75 70 64 61 74 65 5f 68  ite3_preupdate_h
318d0 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
318e0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
318f0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
31900 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31910 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
31920 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
31930 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
31940 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
31950 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
31960 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
31970 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
31980 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
31990 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
319a0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
319b0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
319c0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
319d0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
319e0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
319f0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
31a00 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
31a10 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
31a20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31a30 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
31a40 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
31a50 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
31a60 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
31a70 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
31a80 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
31a90 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
31aa0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
31ab0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
31ac0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
31ad0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
31ae0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
31af0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
31b00 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
31b10 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
31b20 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
31b30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
31b40 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
31b50 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
31b60 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
31b70 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
31b80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
31b90 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
31ba0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
31bb0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
31bc0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
31bd0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31be0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
31bf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
31c00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
31c10 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
31c20 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
31c30 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
31c40 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
31c50 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
31c60 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
31c70 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
31c80 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
31c90 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
31ca0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
31cb0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
31cc0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
31cd0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
31ce0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
31cf0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
31d00 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
31d10 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
31d20 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
31d30 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
31d40 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
31d50 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
31d60 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
31d70 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
31d80 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
31d90 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
31da0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
31db0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
31dc0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
31dd0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
31de0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
31df0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
31e00 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
31e10 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
31e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31e30 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
31e40 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
31e50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31e60 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
31e70 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
31e80 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
31e90 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
31ea0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
31eb0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
31ec0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
31ed0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
31ee0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
31ef0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
31f00 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
31f10 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
31f20 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
31f30 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
31f40 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
31f50 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
31f60 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
31f70 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
31f80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
31f90 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
31fa0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
31fb0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
31fc0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
31fd0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
31fe0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31ff0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32000 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
32010 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
32020 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
32030 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
32040 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
32050 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
32060 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
32070 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
32080 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
32090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
320a0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
320b0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
320c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
320d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
320e0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
320f0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
32100 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
32110 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
32120 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
32130 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
32140 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
32150 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
32160 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
32170 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
32180 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
32190 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
321a0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
321b0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
321c0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
321d0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
321e0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
321f0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
32200 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
32210 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
32220 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
32230 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
32240 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
32250 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
32260 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
32270 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
32280 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
32290 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
322a0 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
322b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
322c0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
322d0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
322e0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
322f0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
32300 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
32310 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
32320 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
32330 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
32340 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
32350 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
32360 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
32370 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
32380 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
32390 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
323a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
323b0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
323c0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
323d0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
323e0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
323f0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
32400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
32410 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
32420 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
32430 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
32440 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
32450 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
32460 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32470 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
32480 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
32490 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
324a0 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
324b0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
324c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
324d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
324e0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
324f0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
32500 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
32510 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
32520 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
32530 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
32540 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
32550 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
32560 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
32570 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
32580 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
32590 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
325a0 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
325b0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
325c0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
325d0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
325e0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
325f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
32600 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
32610 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
32620 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32630 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
32640 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
32650 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
32660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
32670 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
32680 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
32690 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
326a0 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
326b0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
326c0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
326d0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
326e0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
326f0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
32700 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
32710 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
32720 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
32730 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
32740 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
32750 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
32760 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
32770 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
32780 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
32790 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
327a0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
327b0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
327c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
327d0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
327e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
327f0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
32800 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
32810 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
32820 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
32830 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32840 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
32850 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
32860 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
32870 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
32880 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
32890 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
328a0 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
328b0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
328c0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
328d0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
328e0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
328f0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
32900 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
32910 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
32920 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
32930 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
32940 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
32950 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
32960 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
32970 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
32980 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
32990 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
329a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
329b0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
329c0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
329d0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
329e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
329f0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
32a00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
32a10 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c  f SQLite..*/.sql
32a20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
32a30 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
32a40 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
32a50 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
32a60 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
32a70 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
32a80 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
32a90 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
32aa0 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
32ab0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
32ac0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
32ad0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
32ae0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
32af0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
32b00 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
32b10 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
32b20 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
32b30 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
32b40 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
32b50 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
32b60 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
32b70 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
32b80 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
32b90 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
32ba0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
32bb0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
32bc0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b  ap_limit(int N);
32bd0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
32be0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
32bf0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
32c00 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
32c10 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
32c20 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
32c30 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
32c40 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
32c50 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
32c60 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
32c70 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
32c80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32c90 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
32ca0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
32cb0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
32cc0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
32cd0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
32ce0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
32cf0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
32d00 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32d10 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
32d20 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
32d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
32d40 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
32d50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
32d60 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
32d70 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
32d80 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
32d90 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
32da0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
32db0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
32dc0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
32dd0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
32de0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
32df0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
32e00 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
32e10 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
32e20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
32e30 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
32e40 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
32e50 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
32e60 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
32e70 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
32e80 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
32e90 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
32ea0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
32eb0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
32ec0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
32ed0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
32ee0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
32ef0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
32f00 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
32f10 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
32f20 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
32f30 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
32f40 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
32f50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
32f60 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
32f70 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
32f80 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
32f90 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
32fa0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
32fb0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
32fc0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
32fd0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
32fe0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
32ff0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
33000 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
33010 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
33020 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
33030 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
33040 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
33050 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
33060 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
33070 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
33080 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
33090 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
330a0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
330b0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
330c0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
330d0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
330e0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
330f0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
33100 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
33110 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
33120 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
33130 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
33140 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
33150 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
33160 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
33170 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
33180 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
33190 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
331a0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
331b0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
331c0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
331d0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
331e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
331f0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
33200 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
33210 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
33220 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
33230 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
33240 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
33250 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
33260 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
33270 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
33280 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
33290 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
332a0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
332b0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
332c0 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
332d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
332e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
332f0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
33300 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
33310 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
33320 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
33330 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
33340 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
33350 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
33360 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
33370 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
33380 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
33390 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
333a0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
333b0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
333c0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
333d0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
333e0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
333f0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
33400 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
33410 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
33420 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
33430 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
33440 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
33450 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
33460 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
33470 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
33480 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
33490 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
334a0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
334b0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
334c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
334d0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
334e0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
334f0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
33500 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
33510 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
33520 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
33530 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
33540 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
33550 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
33560 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
33570 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
33580 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33590 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
335a0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
335b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
335c0 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
335d0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
335e0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
335f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
33600 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
33610 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
33620 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
33630 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
33640 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
33650 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
33660 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
33670 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
33680 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
33690 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
336a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
336b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
336c0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
336d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
336e0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
336f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
33700 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
33710 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33720 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
33730 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
33740 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
33750 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
33760 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
33770 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
33780 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
33790 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
337a0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
337b0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
337c0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
337d0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
337e0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
337f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
33800 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
33810 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
33820 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
33830 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
33840 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
33850 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
33860 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
33870 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
33880 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
33890 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
338a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
338b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
338c0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
338d0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
338e0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
338f0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
33900 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
33910 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
33920 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
33930 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
33940 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
33950 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
33960 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
33970 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
33980 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
33990 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
339a0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
339b0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
339c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
339d0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
339e0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
339f0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
33a00 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
33a10 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
33a20 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
33a30 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
33a40 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
33a50 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
33a60 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
33a70 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
33a80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
33a90 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
33aa0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
33ab0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
33ac0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
33ad0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
33ae0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
33af0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
33b00 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
33b10 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
33b20 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
33b30 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
33b40 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
33b50 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
33b60 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
33b70 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
33b80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33b90 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
33ba0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
33bb0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
33bc0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
33bd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
33be0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
33bf0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
33c00 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
33c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
33c20 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
33c30 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
33c40 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
33c50 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
33c60 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
33c70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
33c80 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
33c90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
33ca0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
33cb0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
33cc0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
33cd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33ce0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
33cf0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
33d00 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
33d10 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
33d20 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
33d30 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
33d40 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
33d50 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
33d60 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
33d70 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
33d80 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
33d90 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
33da0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
33db0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
33dc0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
33dd0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
33de0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
33df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
33e00 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
33e10 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
33e20 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
33e30 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
33e40 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
33e50 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
33e60 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
33e70 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
33e80 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
33e90 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
33ea0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
33eb0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
33ec0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
33ed0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
33ee0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
33ef0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
33f00 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
33f10 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
33f20 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
33f30 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
33f40 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
33f50 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
33f60 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
33f70 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
33f80 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
33f90 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
33fa0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
33fb0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
33fc0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
33fd0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
33fe0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
33ff0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
34000 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
34010 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
34020 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34030 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34040 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
34050 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
34060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34070 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
34080 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
34090 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
340a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
340b0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
340c0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
340d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
340e0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
340f0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
34100 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
34110 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
34120 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
34130 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
34140 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
34150 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
34160 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
34170 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
34180 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
34190 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
341a0 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
341b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
341c0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
341d0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
341e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
341f0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
34200 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
34210 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
34220 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
34230 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
34240 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
34250 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
34260 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
34270 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
34280 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
34290 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
342a0 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
342b0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
342c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
342d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
342e0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
342f0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
34300 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
34310 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
34320 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
34330 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
34340 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
34350 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
34360 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
34370 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
34380 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
34390 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
343a0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
343b0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
343c0 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
343d0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
343e0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
343f0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
34400 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
34410 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34420 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
34430 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
34440 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
34450 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
34460 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
34470 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
34480 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
34490 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
344a0 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
344b0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
344c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
344d0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
344e0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
344f0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
34500 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
34510 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
34520 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
34530 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
34540 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
34550 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34560 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
34570 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
34580 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
34590 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
345a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
345b0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
345c0 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
345d0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
345e0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
345f0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
34600 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
34610 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
34620 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
34630 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
34640 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
34650 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
34660 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
34670 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
34680 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
34690 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
346a0 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
346b0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sion()]..*/.int 
346c0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
346d0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
346e0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
346f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34700 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
34710 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
34720 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ading.**.** ^Thi
34730 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61  s interface disa
34740 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74  bles all automat
34750 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72  ic extensions pr
34760 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69  eviously.** regi
34770 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
34780 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
34790 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  sion()]..*/.void
347a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
347b0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
347c0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
347d0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
347e0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
347f0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
34800 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
34810 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
34820 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
34830 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
34840 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
34850 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
34860 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
34870 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
34880 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
34890 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
348a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
348b0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
348c0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
348d0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
348e0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
348f0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
34900 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
34910 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
34920 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
34930 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
34940 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
34950 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
34960 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
34970 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
34980 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
34990 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
349a0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
349b0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
349c0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
349d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
349e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
349f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
34a00 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
34a10 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
34a20 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
34a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34a40 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
34a50 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
34a60 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
34a70 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
34a80 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
34a90 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
34aa0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
34ab0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
34ac0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
34ad0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
34ae0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
34af0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
34b00 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
34b10 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
34b20 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
34b30 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
34b40 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
34b50 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
34b60 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
34b70 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
34b80 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
34b90 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
34ba0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
34bb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
34bc0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
34bd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
34be0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
34bf0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
34c00 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
34c10 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
34c20 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
34c30 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
34c40 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
34c50 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
34c60 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
34c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
34c80 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
34c90 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
34ca0 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
34cb0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
34cc0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
34cd0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
34ce0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
34cf0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
34d00 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
34d10 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
34d20 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
34d30 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
34d40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34d50 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
34d60 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
34d70 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
34d80 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
34d90 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
34da0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
34db0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
34dc0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
34dd0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
34de0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
34df0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
34e00 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
34e10 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
34e20 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
34e30 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
34e40 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34e50 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
34e60 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
34e70 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
34e80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34e90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
34ea0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
34eb0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34ec0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
34ed0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
34ee0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34ef0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
34f00 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
34f10 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34f20 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
34f30 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
34f40 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
34f50 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
34f60 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
34f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
34f80 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
34f90 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
34fa0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
34fb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34fc0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
34fd0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
34fe0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
34ff0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
35000 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35010 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
35020 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
35030 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
35040 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
35050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
35060 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
35070 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
35080 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
35090 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
350a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
350b0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
350c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
350d0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
350e0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
350f0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
35100 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
35110 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35120 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
35130 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
35140 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
35150 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
35160 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
35170 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
35180 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
35190 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
351a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
351b0 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
351c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
351d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
351e0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
351f0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
35200 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
35210 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
35220 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
35230 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
35240 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
35250 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
35260 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
35270 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59  formation.** KEY
35280 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
35290 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20  ndex_info.**.** 
352a0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
352b0 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
352c0 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
352d0 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61  ctures is used a
352e0 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65  s part.** of the
352f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
35300 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
35310 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
35320 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
35330 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
35340 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65  m the [xBestInde
35350 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  x].** method of 
35360 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
35370 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66   module].  The f
35380 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
35390 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
353a0 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
353b0 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
353c0 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
353d0 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
353e0 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
353f0 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
35400 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
35410 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  ^(The aConstrain
35420 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
35430 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
35440 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
35450 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e form:.**.** <b
35460 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e  lockquote>column
35470 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71   OP expr</blockq
35480 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  uote>.**.** wher
35490 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
354a0 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
354b0 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65   &gt;=.)^  ^(The
354c0 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
354d0 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
354e0 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
354f0 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20  [].op using one 
35500 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  of the.** [SQLIT
35510 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
35520 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49  NT_EQ | SQLITE_I
35530 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
35540 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e   values].)^.** ^
35550 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68  (The index of th
35560 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
35570 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72  ed in.** aConstr
35580 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29  aint[].iColumn.)
35590 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74  ^  ^(aConstraint
355a0 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55  [].usable is TRU
355b0 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72  E if the.** expr
355c0 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61   on the right-ha
355d0 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65  nd side can be e
355e0 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68  valuated (and th
355f0 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  us the constrain
35600 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20  t.** is usable) 
35610 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20  and false if it 
35620 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cannot.)^.**.** 
35630 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61  ^The optimizer a
35640 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
35650 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
35660 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
35670 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
35680 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
35690 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
356a0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
356b0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
356c0 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
356d0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
356e0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
356f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
35700 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65  ossible..** ^The
35710 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
35720 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
35730 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
35740 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  erms that are.**
35750 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65   relevant to the
35760 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
35770 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20  ual table being 
35780 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  queried..**.** ^
35790 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  Information abou
357a0 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  t the ORDER BY c
357b0 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20  lause is stored 
357c0 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a  in aOrderBy[]..*
357d0 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20  * ^Each term of 
357e0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
357f0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
35800 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65  ..**.** The [xBe
35820 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20  stIndex] method 
35830 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
35840 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
35850 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
35860 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
35870 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
35880 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20  o xFilter.  ^If 
35890 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
358a0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
358b0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
358c0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
358d0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
358e0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
358f0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
35900 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
35910 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f   argv.  ^(If aCo
35920 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
35930 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
35940 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
35950 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
35960 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
35970 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
35980 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
35990 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
359a0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29  gain by SQLite.)
359b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78  ^.**.** ^The idx
359c0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
359d0 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
359e0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
359f0 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74  to the.** [xFilt
35a00 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e  er] method..** ^
35a10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
35a20 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
35a30 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f   idxPtr if and o
35a40 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f  nly if.** needTo
35a50 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
35a60 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  ue..**.** ^The o
35a70 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
35a80 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
35a90 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f   from [xFilter]/
35aa0 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63  [xNext] will occ
35ab0 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
35ac0 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
35ad0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
35ae0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
35af0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
35b00 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
35b10 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
35b20 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43   ^The estimatedC
35b30 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20  ost value is an 
35b40 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20  estimate of the 
35b50 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68  cost of doing th
35b60 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20  e.** particular 
35b70 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20  lookup.  A full 
35b80 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20  scan of a table 
35b90 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73  with N entries s
35ba0 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20  hould have.** a 
35bb0 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69  cost of N.  A bi
35bc0 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61  nary search of a
35bd0 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72   table of N entr
35be0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ies should have 
35bf0 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70  a.** cost of app
35c00 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e  roximately log(N
35c10 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
35c20 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
35c30 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f  {.  /* Inputs */
35c40 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  .  int nConstrai
35c50 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  nt;           /*
35c60 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69   Number of entri
35c70 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  es in aConstrain
35c80 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  t */.  struct sq
35c90 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
35ca0 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e  traint {.     in
35cb0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
35cc0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
35cd0 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73  n on left-hand s
35ce0 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e  ide of constrain
35cf0 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  t */.     unsign
35d00 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
35d10 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
35d20 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20  t operator */.  
35d30 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
35d40 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20   usable;     /* 
35d50 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e  True if this con
35d60 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c  straint is usabl
35d70 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54  e */.     int iT
35d80 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20  ermOffset;      
35d90 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
35da0 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e  rnally - xBestIn
35db0 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72  dex should ignor
35dc0 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  e */.  } *aConst
35dd0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
35de0 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
35df0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
35e00 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20  raints */.  int 
35e10 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
35e20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
35e30 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
35e40 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35e50 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
35e60 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
35e70 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
35e80 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
35e90 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
35ea0 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
35eb0 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
35ec0 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
35ed0 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
35ee0 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
35ef0 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20  *aOrderBy;      
35f00 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
35f10 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
35f20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  */.  /* Outputs 
35f30 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
35f40 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
35f50 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
35f60 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
35f70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
35f80 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
35f90 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
35fa0 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
35fb0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
35fc0 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
35fd0 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
35fe0 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
35ff0 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  int */.  } *aCon
36000 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20  straintUsage;.  
36010 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20  int idxNum;     
36020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
36030 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65  mber used to ide
36040 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20  ntify the index 
36050 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74  */.  char *idxSt
36060 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
36070 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
36080 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
36090 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
360a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f   */.  int needTo
360b0 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20  FreeIdxStr;     
360c0 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20   /* Free idxStr 
360d0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  using sqlite3_fr
360e0 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a  ee() if true */.
360f0 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e    int orderByCon
36100 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20  sumed;       /* 
36110 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69  True if output i
36120 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65  s already ordere
36130 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73  d */.  double es
36140 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
36150 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63    /* Estimated c
36160 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ost of using thi
36170 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f  s index */.};../
36180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
36190 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e  irtual Table Con
361a0 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72  straint Operator
361b0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
361c0 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65  se macros define
361d0 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61  d the allowed va
361e0 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lues for the.** 
361f0 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69  [sqlite3_index_i
36200 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74  nfo].aConstraint
36210 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61  [].op field.  Ea
36220 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 65  ch value represe
36230 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74  nts.** an operat
36240 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74 20  or that is part 
36250 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  of a constraint 
36260 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52  term in the wHER
36270 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61  E clause of.** a
36280 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65 73   query that uses
36290 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
362a0 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e]..*/.#define S
362b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
362c0 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
362d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
362e0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
362f0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
36300 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36310 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
36320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36330 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
36340 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
36350 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
36360 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
36370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36380 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
36390 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
363a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
363b0 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
363c0 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
363d0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
363e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
363f0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
36400 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
36410 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
36420 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
36430 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
36440 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
36450 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
36460 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
36470 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
36480 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
36490 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
364a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
364b0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
364c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
364d0 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
364e0 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
364f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36500 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
36510 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
36520 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
36530 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
36540 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
36550 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
36560 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
36570 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
36580 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
36590 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
365a0 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
365b0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
365c0 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
365d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
365e0 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
365f0 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
36600 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
36610 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
36620 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
36630 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
36640 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
36650 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
36660 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
36670 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
36680 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
36690 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
366a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
366b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
366c0 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
366d0 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
366e0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
366f0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
36700 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
36710 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
36720 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
36730 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
36740 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
36750 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
36760 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
36770 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
36780 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
36790 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
367a0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
367b0 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
367c0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
367d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
367e0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
367f0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68  () fails..** ^Th
36800 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36810 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74  _module().** int
36820 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
36830 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  lent to sqlite3_
36840 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
36850 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a  () with a NULL.*
36860 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f  * destructor..*/
36870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
36880 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
36890 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
368a0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
368b0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
368c0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
368d0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
368e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
368f0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
36900 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
36910 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
36920 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
36930 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
36940 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
36950 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
36960 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
36970 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
36980 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
36990 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
369a0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
369b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
369c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
369d0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
369e0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
369f0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
36a00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
36a10 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
36a20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
36a30 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
36a40 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
36a50 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
36a60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
36a70 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
36a80 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
36a90 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
36aa0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
36ab0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
36ac0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
36ad0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
36ae0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
36af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36b00 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36b10 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a  nstance Object.*
36b20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
36b30 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
36b40 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
36b50 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
36b60 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
36b70 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
36b80 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20   this object to 
36b90 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69  describe a parti
36ba0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a  cular instance.*
36bb0 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
36bc0 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20  l table].  Each 
36bd0 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
36be0 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
36bf0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
36c00 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
36c10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
36c20 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20  .** The purpose 
36c30 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
36c40 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
36c50 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
36c60 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f  hat are.** commo
36c70 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  n to all module 
36c80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
36c90 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20  .**.** ^Virtual 
36ca0 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
36cb0 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
36cc0 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
36cd0 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
36ce0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36cf0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36d00 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
36d10 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
36d20 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
36d30 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
36d40 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
36d50 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
36d60 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
36d70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
36d80 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
36d90 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74  o zErrMsg.  ^Aft
36da0 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
36db0 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
36dc0 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63  ered up to the c
36dd0 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  lient applicatio
36de0 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  n, the string wi
36df0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
36e00 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20  lly.** freed by 
36e10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
36e20 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  nd the zErrMsg f
36e30 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72  ield will be zer
36e40 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  oed..*/.struct s
36e50 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
36e60 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
36e70 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
36e80 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
36e90 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
36ea0 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
36eb0 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
36ec0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20            /* NO 
36ed0 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20  LONGER USED */. 
36ee0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
36ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f00 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
36f10 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
36f20 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
36f30 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
36f40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
36f50 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
36f60 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
36f70 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
36f80 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
36f90 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
36fa0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
36fb0 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
36fc0 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c  _cursor {virtual
36fd0 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a   table cursor}.*
36fe0 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
36ff0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
37000 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
37010 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
37020 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f   of the.** follo
37030 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74  wing structure t
37040 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f  o describe curso
37050 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e  rs that point in
37060 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75  to the.** [virtu
37070 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72  al table] and ar
37080 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f  e used.** to loo
37090 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69  p through the vi
370a0 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75  rtual table.  Cu
370b0 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65  rsors are create
370c0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
370d0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
370e0 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65  Open | xOpen] me
370f0 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
37100 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72  le and are destr
37110 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  oyed.** by the [
37120 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
37130 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20  Close | xClose] 
37140 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73  method.  Cursors
37150 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20   are used.** by 
37160 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b  the [xFilter], [
37170 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20  xNext], [xEof], 
37180 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b  [xColumn], and [
37190 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a  xRowid] methods.
371a0 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ** of the module
371b0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
371c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
371d0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
371e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
371f0 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
37200 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
37210 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
37220 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
37230 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
37240 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
37250 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
37260 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
37270 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
37280 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
37290 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
372a0 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
372b0 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
372c0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
372d0 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
372e0 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
372f0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37300 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37310 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37320 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37330 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37340 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
37350 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
37360 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
37370 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61  ^The [xCreate] a
37380 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
37390 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
373a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
373b0 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
373c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
373d0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
373e0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
373f0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
37400 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
37410 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
37420 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
37430 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
37440 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
37450 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
37460 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a  char *zSQL);../*
37470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76  .** CAPI3REF: Ov
37480 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f  erload A Functio
37490 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20  n For A Virtual 
374a0 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69  Table.**.** ^(Vi
374b0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
374c0 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61   provide alterna
374d0 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
374e0 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e  ions of function
374f0 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  s.** using the [
37500 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d  xFindFunction] m
37510 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69  ethod of the [vi
37520 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
37530 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c  le].  .** But gl
37540 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
37550 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
37560 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
37570 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
37580 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a  erloaded.)^.**.*
37590 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b  * ^(This API mak
375a0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
375b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
375c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
375d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
375e0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
375f0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
37600 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
37610 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
37620 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
37630 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
37640 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
37650 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69  eated.)^  ^The i
37660 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
37670 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
37680 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
37690 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
376a0 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
376b0 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
376c0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
376d0 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
376e0 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
376f0 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
37700 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68  s to be a placeh
37710 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
37720 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
37730 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76  oaded.** by a [v
37740 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
37750 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
37760 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
37770 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
37780 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
37790 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
377a0 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
377b0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
377c0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
377d0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
377e0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
377f0 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
37800 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
37810 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
37820 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
37830 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
37840 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
37850 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
37860 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
37870 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
37880 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
37890 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
378a0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
378b0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
378c0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
378d0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
378e0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
378f0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
37900 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
37910 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
37920 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
37930 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
37940 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
37950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37960 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
37970 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59  Open BLOB.** KEY
37980 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
37990 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
379a0 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
379b0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
379c0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
379d0 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
379e0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
379f0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
37a00 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
37a10 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
37a20 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74  rmed..** ^Object
37a30 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61  s of this type a
37a40 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  re created by [s
37a50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
37a60 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72  ()].** and destr
37a70 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
37a80 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
37a90 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
37aa0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
37ab0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
37ac0 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
37ad0 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
37ae0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
37af0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
37b00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f  tions of the BLO
37b10 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  B..** ^The [sqli
37b20 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
37b30 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
37b40 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
37b50 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65  the BLOB in byte
37b60 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
37b70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
37b80 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
37b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ba0 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
37bb0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
37bc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
37bd0 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61  terfaces opens a
37be0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20   [BLOB handle | 
37bf0 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42  handle] to the B
37c00 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69  LOB located.** i
37c10 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75  n row iRow, colu
37c20 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c  mn zColumn, tabl
37c30 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
37c40 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20  base zDb;.** in 
37c50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
37c60 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20   same BLOB that 
37c70 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
37c80 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
37c90 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
37ca0 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
37cb0 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72  .zTable WHERE [r
37cc0 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a  owid] = iRow;.**
37cd0 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
37ce0 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61  ^If the flags pa
37cf0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
37d00 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c  ero, then the BL
37d10 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
37d20 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69   read.** and wri
37d30 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69  te access. ^If i
37d40 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42  t is zero, the B
37d50 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
37d60 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a  r read access..*
37d70 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73  * ^It is not pos
37d80 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
37d90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
37da0 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20  art of an index 
37db0 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b  or primary .** k
37dc0 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20  ey for writing. 
37dd0 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  ^If [foreign key
37de0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72   constraints] ar
37df0 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73  e enabled, it is
37e00 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c   .** not possibl
37e10 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
37e20 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
37e30 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d  of a [child key]
37e40 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a   for writing..**
37e50 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
37e60 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
37e70 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   is not the file
37e80 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69  name that contai
37e90 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
37ea0 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68  se but rather th
37eb0 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
37ec0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37ed0 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20  that.** appears 
37ee0 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79  after the AS key
37ef0 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61  word when the da
37f00 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63  tabase is connec
37f10 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43  ted using [ATTAC
37f20 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  H]..** ^For the 
37f30 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37f40 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  le, the database
37f50 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e   name is "main".
37f60 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61  .** ^For TEMP ta
37f70 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
37f80 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
37f90 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75  "..**.** ^(On su
37fa0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
37fb0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  K] is returned a
37fc0 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42  nd the new [BLOB
37fd0 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
37fe0 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f  ten.** to *ppBlo
37ff0 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  b. Otherwise an 
38000 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
38010 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70  returned and *pp
38020 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74  Blob is set.** t
38030 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  o be a null poin
38040 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20  ter.)^.** ^This 
38050 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
38060 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38070 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f  ection] error co
38080 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
38090 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
380a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
380b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
380c0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
380d0 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74  related.** funct
380e0 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74  ions. ^Note that
380f0 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72   the *ppBlob var
38100 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20  iable is always 
38110 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61  initialized in a
38120 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b  .** way that mak
38130 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e  es it safe to in
38140 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  voke [sqlite3_bl
38150 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a  ob_close()] on *
38160 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64  ppBlob.** regard
38170 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
38180 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  ess or failure o
38190 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
381a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72  **.** ^(If the r
381b0 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
381c0 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
381d0 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
381e0 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
381f0 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
38200 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
38210 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
38220 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
38230 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
38240 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
38250 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
38260 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
38270 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
38280 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
38290 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
382a0 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
382b0 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e  le is open on.)^
382c0 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73  .** ^Calls to [s
382d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
382e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
382f0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66  _blob_write()] f
38300 6f 72 0a 2a 2a 20 61 6e 20 65 78 70 69 72 65 64  or.** an expired
38310 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
38320 6c 20 77 69 74 68 20 61 20 72 65 74 75 72 6e 20  l with a return 
38330 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
38340 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61  ABORT]..** ^(Cha
38350 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74  nges written int
38360 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74  o a BLOB prior t
38370 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72  o the BLOB expir
38380 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  ing are not.** r
38390 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
383a0 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  e expiration of 
383b0 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20  the BLOB.  Such 
383c0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65  changes will eve
383d0 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69  ntually.** commi
383e0 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63  t if the transac
383f0 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74  tion continues t
38400 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a  o completion.)^.
38410 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b  **.** ^Use the [
38420 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
38430 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
38440 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
38450 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
38460 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54  opened blob.  ^T
38470 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
38480 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61  b may not be cha
38490 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  nged by this.** 
384a0 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20  interface.  Use 
384b0 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c  the [UPDATE] SQL
384c0 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e   command to chan
384d0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
384e0 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  .** blob..**.** 
384f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69  ^The [sqlite3_bi
38500 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61  nd_zeroblob()] a
38510 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
38520 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69  lt_zeroblob()] i
38530 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64  nterfaces.** and
38540 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a   the built-in [z
38550 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e  eroblob] SQL fun
38560 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ction can be use
38570 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a  d, if desired,.*
38580 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65  * to create an e
38590 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65  mpty, zero-fille
385a0 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20  d blob in which 
385b0 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  to read or write
385c0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69   using.** this i
385d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
385e0 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75  To avoid a resou
385f0 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20  rce leak, every 
38600 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
38610 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75  e] should eventu
38620 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61  ally.** be relea
38630 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  sed by a call to
38640 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
38650 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  lose()]..*/.int 
38660 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
38670 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
38680 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
38690 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
386a0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
386b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
386c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
386d0 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
386e0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
386f0 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
38700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 6f  .** CAPI3REF: Mo
38710 76 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65  ve a BLOB Handle
38720 20 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a   to a New Row.**
38730 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
38740 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6d 6f  on is used to mo
38750 76 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62  ve an existing b
38760 6c 6f 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 68  lob handle so th
38770 61 74 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20  at it points.** 
38780 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20 72  to a different r
38790 6f 77 20 6f 66 20 74 68 65 20 73 61 6d 65 20 64  ow of the same d
387a0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 5e  atabase table. ^
387b0 54 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20 69  The new row is i
387c0 64 65 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79 20  dentified.** by 
387d0 74 68 65 20 72 6f 77 69 64 20 76 61 6c 75 65 20  the rowid value 
387e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
387f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f  cond argument. O
38800 6e 6c 79 20 74 68 65 20 72 6f 77 20 63 61 6e 20  nly the row can 
38810 62 65 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e  be.** changed. ^
38820 54 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  The database, ta
38830 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f  ble and column o
38840 6e 20 77 68 69 63 68 20 74 68 65 20 62 6c 6f 62  n which the blob
38850 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a   handle is open.
38860 2a 2a 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61  ** remain the sa
38870 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78  me. Moving an ex
38880 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64  isting blob hand
38890 6c 65 20 74 6f 20 61 20 6e 65 77 20 72 6f 77 20  le to a new row 
388a0 63 61 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65 72  can be.** faster
388b0 20 74 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68   than closing th
388c0 65 20 65 7