/ Hex Artifact Content
Login

Artifact c095996e68e0082f674f32e68ca909fc24196a2a:


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 2c 0a   result codes],.
3e40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
3e50: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
3e60: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
3e70: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
3e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
3e90: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
3ea0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
3eb0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
3ec0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
3ed0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
3ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
3ef0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
3f00: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
3f10: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
3f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3f30: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
3f40: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
3f50: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
3f60: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3f70: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
3f80: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
3f90: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fb0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
3fc0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
3fd0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
3fe0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
3ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4000: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4010: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4020: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4040: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4050: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4060: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4070: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4080: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4090: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
40a0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
40c0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
40d0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
40e0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
40f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4100: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4110: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4120: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4130: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4140: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4160: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4170: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4180: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4190: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
41a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
41b0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
41c0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
41d0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
41e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
41f0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4200: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4210: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4220: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4240: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4250: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4260: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4270: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4290: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
42a0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
42b0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
42c0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
42d0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
42e0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
42f0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4300: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4310: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4320: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4330: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4350: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4360: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4370: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4380: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4390: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
43a0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
43b0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
43c0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
43e0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
43f0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4400: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4410: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4420: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4430: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4440: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4460: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4470: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4480: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
44a0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
44b0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
44c0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
44d0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
44f0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4500: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4510: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4520: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4530: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4540: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4550: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4570: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4580: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4590: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
45a0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
45b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
45c0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
45d0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
45e0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
45f0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4600: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4610: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4620: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4630: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4650: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4660: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4670: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4680: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4690: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
46a0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
46b0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
46c0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
46d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
46e0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
46f0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4700: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4710: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4720: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4730: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4740: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4750: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4760: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4770: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4780: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4790: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
47a0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
47b0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
47c0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
47d0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
47e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
47f0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4800: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4810: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4820: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4840: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4850: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4860: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4870: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4880: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4890: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
48a0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
48b0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
48c0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
48d0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
48e0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
48f0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4900: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4910: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4920: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4930: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4940: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4950: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4960: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4970: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4980: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4990: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
49a0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
49b0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
49c0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
49d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
49e0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
49f0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4a00: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4a10: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4a20: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4a30: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4a40: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4a50: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4a60: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4a70: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4a80: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4a90: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4aa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4ab0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4ac0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4ad0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ae0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4af0: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4b00: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4b20: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4b60: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4b70: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4b80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4b90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ba0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4bb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4bc0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4bd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4be0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4bf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c00: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c20: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c40: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4c60: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4c80: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ca0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4cc0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ce0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d00: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
4d10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d20: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
4d30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d40: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
4d50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4d60: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
4d70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4d80: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
4d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4da0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
4db0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4dc0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4de0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
4df0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e00: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
4e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e20: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
4e30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e40: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
4e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e60: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
4e70: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
4e80: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
4e90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ea0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
4eb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ec0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
4ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ee0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
4ef0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f00: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
4f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f20: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
4f30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f40: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
4f50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f60: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
4f70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f80: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
4f90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fa0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
4fb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4fc0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
4fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fe0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
4ff0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5000: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5020: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5030: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5040: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5060: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5070: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5080: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5090: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
50a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
50b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
50c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
50d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
50e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
50f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5100: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5120: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5130: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5140: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5160: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5170: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5180: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
51a0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
51b0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
51c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
51d0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
51e0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
51f0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5200: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5210: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5220: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5230: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5240: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5250: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5260: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5280: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5290: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
52a0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
52b0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
52d0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
52e0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
52f0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5300: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5320: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5330: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5340: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5350: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5370: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5380: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5390: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53b0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
53c0: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
53d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53f0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5400: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5410: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5430: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5440: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5450: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5460: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5480: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5490: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
54a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
54c0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
54d0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
54e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5500: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5510: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5520: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5530: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5540: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5550: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5560: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5580: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5590: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
55a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
55c0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
55d0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
55e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5600: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5610: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5620: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5640: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5650: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5660: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5670: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5690: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
56a0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
56b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
56c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
56e0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
56f0: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
5700: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5710: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5730: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
5740: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
5750: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5760: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5780: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
5790: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
57a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
57b0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
57c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
57d0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
57e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
57f0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5800: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
5810: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
5820: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
5830: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
5840: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
5850: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
5860: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
5870: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
5880: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
5890: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
58a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
58b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
58c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
58d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
58e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
58f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5900: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
5910: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
5920: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5930: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5940: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
5950: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
5960: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5970: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5980: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5990: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
59a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
59b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
59c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
59d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
59e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
59f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5a00: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5a10: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5a30: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
5a40: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
5a50: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
5a60: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
5a70: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5a80: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5a90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5aa0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5ab0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5ac0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5ad0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5ae0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5af0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5b00: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5b10: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5b20: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5b30: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5b40: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
5b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b80: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ba0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
5bb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5bd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bf0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5c00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c10: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
5c20: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c40: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5c50: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c60: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5c70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c80: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
5c90: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5cb0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5cc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5cd0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5ce0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5cf0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5d00: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
5d10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5d20: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5d30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5d40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5d50: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5d60: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
5d70: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5d80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5d90: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
5da0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5dc0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
5dd0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
5de0: 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000800../*.** CA
5df0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5e00: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
5e10: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
5e20: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
5e30: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
5e40: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
5e50: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
5e60: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
5e70: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
5e80: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
5e90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
5ea0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
5eb0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5ec0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
5ed0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
5ee0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5ef0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5f10: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
5f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5f30: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
5f40: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
5f50: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5f60: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
5f70: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
5f80: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
5f90: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
5fa0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
5fb0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
5fc0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
5fd0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5fe0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
5ff0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6000: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6010: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6020: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6030: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6040: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6050: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6060: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6070: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6080: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6090: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
60a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
60b0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
60c0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
60d0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
60e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
60f0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6100: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6110: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6120: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6130: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6140: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6150: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6160: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6170: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6180: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6190: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
61a0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
61b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
61c0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
61d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
61e0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
61f0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6200: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6210: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6220: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6230: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6240: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6250: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6260: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6270: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6280: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6290: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
62a0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
62b0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
62c0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
62d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
62e0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
62f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6300: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6310: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6320: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6330: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6340: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6350: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6360: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6370: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6380: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6390: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
63a0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
63b0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
63c0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
63d0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
63e0: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
63f0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6400: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6410: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6420: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6430: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6440: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6450: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6460: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6470: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6490: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
64a0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
64b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
64c0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
64d0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
64e0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
64f0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6500: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6510: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6520: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6530: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6540: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6550: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6560: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6570: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6580: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6590: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
65a0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
65b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
65c0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
65d0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
65e0: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
65f0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6600: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6610: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6620: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6630: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6640: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6650: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6660: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6670: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6680: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6690: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
66a0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
66b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
66c0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
66d0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
66e0: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
66f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6700: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6710: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6720: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6730: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6740: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6750: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6760: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6770: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6780: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6790: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
67a0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
67b0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
67c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
67d0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
67e0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
67f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6800: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6810: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6820: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6830: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6840: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6850: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6860: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6870: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
6880: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
6890: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
68a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
68b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
68c0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
68d0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
68e0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
68f0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
6900: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6910: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
6920: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
6930: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
6940: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
6950: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
6960: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
6970: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
6980: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6990: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
69a0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
69b0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
69c0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
69d0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
69e0: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
69f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
6a00: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
6a10: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
6a20: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
6a30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
6a40: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
6a50: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
6a60: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6a70: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
6a80: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
6a90: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
6aa0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6ab0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
6ac0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
6ad0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
6ae0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
6af0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
6b00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
6b10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
6b20: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
6b30: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
6b40: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
6b50: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
6b60: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
6b70: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
6b80: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
6b90: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
6ba0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
6bb0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
6bc0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
6bd0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
6be0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
6bf0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
6c00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6c10: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
6c20: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6c30: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
6c40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6c50: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
6c60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6c70: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
6c80: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
6c90: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
6ca0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
6cb0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
6cc0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
6cd0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
6ce0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
6cf0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
6d00: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
6d10: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
6d20: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
6d30: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
6d40: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
6d50: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
6d60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
6d70: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
6d80: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
6d90: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
6da0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
6db0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
6dc0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
6dd0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
6de0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
6df0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
6e00: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
6e10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
6e20: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
6e30: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
6e40: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
6e50: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6e60: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
6e70: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
6e80: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
6e90: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
6ea0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
6eb0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
6ec0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
6ed0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
6ee0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
6ef0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
6f00: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
6f10: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
6f20: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
6f30: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
6f40: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
6f50: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
6f60: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
6f70: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
6f80: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
6f90: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
6fa0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
6fb0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
6fc0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
6fd0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
6fe0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
6ff0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7000: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7010: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7020: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7030: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7040: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7050: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7060: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7080: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7090: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
70a0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
70b0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
70c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
70d0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
70e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
70f0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7100: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7110: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7120: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7130: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7140: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7150: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7160: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7170: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7180: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7190: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
71a0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
71b0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
71c0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
71d0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
71e0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
71f0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7200: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7210: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7220: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7230: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7240: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7250: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7260: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7270: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7280: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7290: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
72a0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
72b0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
72c0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
72d0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
72e0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
72f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7300: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7310: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7320: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7330: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7340: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7350: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7360: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7370: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7380: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
73b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73c0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
73f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7400: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7410: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7420: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7430: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7440: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7450: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7460: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7470: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7480: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7490: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
74a0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
74b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
74c0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
74d0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
74e0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
74f0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7500: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7510: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7520: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7530: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7540: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7550: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7560: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7570: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7580: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7590: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
75a0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
75b0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
75c0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
75d0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
75e0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
75f0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7600: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7610: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7620: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7630: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7640: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7650: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7660: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7670: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7680: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7690: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
76a0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
76b0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
76c0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
76d0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
76e0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
76f0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7700: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7710: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7720: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7730: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7740: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7750: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7760: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7770: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7780: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7790: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
77a0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
77b0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
77c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
77d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
77e0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
77f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7800: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7810: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7820: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7830: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7840: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7850: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7860: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
7880: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7890: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
78a0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
78b0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
78c0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
78d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
78e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
78f0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
7900: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
7910: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
7920: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
7930: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7940: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7950: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
7960: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
7970: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
7980: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
7990: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
79a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
79b0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
79c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79d0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
79e0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
79f0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
7a00: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
7a10: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
7a20: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
7a30: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7a40: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
7a50: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
7a60: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
7a70: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
7a80: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
7a90: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
7aa0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
7ab0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
7ac0: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
7ad0: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
7ae0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
7af0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
7b00: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
7b10: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
7b20: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
7b30: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
7b40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
7b50: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
7b60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7b70: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
7b80: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b90: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7ba0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
7bb0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
7bc0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
7bd0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
7be0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
7bf0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
7c00: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
7c10: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
7c20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7c30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7c40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7c50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7c60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7c70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7c80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
7c90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7ca0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
7cb0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
7cc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7cd0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
7ce0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7cf0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7d00: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7d10: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7d20: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7d30: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7d40: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7d50: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7d60: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7d70: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7d80: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
7d90: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
7da0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7db0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7dc0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7dd0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7de0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7df0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7e00: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7e10: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7e20: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7e30: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7e40: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7e50: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7e60: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7e70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7e80: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
7e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7ea0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
7eb0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
7ec0: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
7ed0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
7ee0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
7ef0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
7f00: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
7f10: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
7f20: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
7f30: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
7f40: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
7f50: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
7f60: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
7f70: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
7f80: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
7f90: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
7fa0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
7fb0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
7fc0: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
7fd0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
7fe0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
7ff0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   faster..**.** T
8000: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8010: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8030: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8040: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8050: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8060: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8070: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8080: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8090: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
80a0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
80b0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
80c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
80d0: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
80e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
80f0: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8100: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8110: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8120: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8130: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8140: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8150: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8160: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8170: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
8180: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
8190: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
81a0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
81b0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
81c0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
81d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
81e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
81f0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8200: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
8210: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
8220: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
8230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
8240: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
8250: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
8260: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8270: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8280: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8290: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
82a0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
82b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
82c0: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
82d0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
82e0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
82f0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
8300: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
8310: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
8320: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
8330: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
8340: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
8350: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
8360: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8370: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
8380: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
8390: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
83a0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
83b0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
83c0: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
83d0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
83e0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
83f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
8400: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8410: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
8420: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
8430: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
8440: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
8450: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
8460: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
8470: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
8480: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
8490: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
84a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
84b0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
84c0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
84d0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
84e0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
84f0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
8500: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
8510: 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69 6e   it.  .*/.#defin
8520: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
8530: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
8540: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8550: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
8560: 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  LE      2.#defin
8570: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
8580: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
8590: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
85a0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
85b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
85c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
85d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
85e0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
85f0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8600: 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e  E       6.#defin
8610: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
8620: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
8630: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
8640: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
8650: 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a  TED     8.../*.*
8660: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
8670: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
8680: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
8690: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
86a0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
86b0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
86c0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
86d0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
86e0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
86f0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
8700: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
8710: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
8720: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
8730: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
8740: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
8750: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
8760: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
8770: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
8780: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
8790: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
87a0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
87b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
87c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
87d0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
87e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
87f0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
8800: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
8810: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
8820: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
8830: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
8840: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
8850: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
8860: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
8870: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
8880: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
8890: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
88a0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
88b0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
88c0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
88d0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
88e0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
88f0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
8900: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
8910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
8920: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
8930: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
8940: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
8950: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
8960: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
8970: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
8980: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
8990: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
89a0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
89b0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
89c0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
89d0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
89e0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
89f0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
8a00: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
8a10: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
8a20: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
8a30: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
8a40: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
8a50: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
8a60: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
8a70: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
8a80: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
8a90: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
8aa0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
8ab0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
8ac0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
8ad0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
8ae0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
8af0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
8b00: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
8b10: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
8b20: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
8b30: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
8b40: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
8b50: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
8b60: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
8b70: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
8b80: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
8b90: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
8ba0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
8bb0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
8bc0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
8bd0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
8be0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
8bf0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
8c00: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
8c10: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
8c20: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
8c30: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
8c40: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
8c50: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
8c60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
8c70: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
8c80: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
8c90: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
8ca0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
8cb0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
8cc0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
8cd0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
8ce0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
8cf0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
8d00: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
8d10: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
8d20: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
8d30: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
8d40: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
8d50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
8d60: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
8d70: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
8d80: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8d90: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
8da0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
8db0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
8dc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
8dd0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
8de0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
8df0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
8e00: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
8e10: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
8e20: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
8e30: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
8e40: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
8e50: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
8e60: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
8e70: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8e80: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
8e90: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
8ea0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
8eb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
8ec0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
8ed0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
8ee0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
8ef0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
8f00: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
8f10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
8f20: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
8f30: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
8f40: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
8f50: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
8f60: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70  e than.** 10 alp
8f70: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
8f80: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
8f90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
8fa0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8fb0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8fc0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
8fd0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
8fe0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
8ff0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
9000: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
9010: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
9020: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9030: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
9040: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
9050: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
9060: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
9070: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
9080: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
9090: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
90a0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
90b0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
90c0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
90d0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
90e0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
90f0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
9100: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
9110: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
9120: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
9130: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
9140: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
9150: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
9160: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
9170: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
9180: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9190: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
91a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
91b0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
91c0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
91d0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
91e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
91f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
9200: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
9210: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9220: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
9230: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
9240: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
9250: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
9260: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
9270: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
9280: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
9290: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
92a0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
92b0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
92c0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
92d0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
92e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
92f0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
9300: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
9310: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
9320: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
9330: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
9340: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
9350: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
9360: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
9370: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
9380: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
9390: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
93a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
93b0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
93c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
93d0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
93e0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
93f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
9400: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9410: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
9420: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9430: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
9440: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
9450: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
9460: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9470: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
9480: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
9490: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
94a0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
94b0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
94c0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
94d0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
94e0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
94f0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
9500: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
9510: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
9520: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
9530: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
9540: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
9550: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
9560: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
9570: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
9580: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
9590: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
95a0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
95b0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
95c0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
95d0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
95e0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
95f0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
9600: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
9610: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
9620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
9630: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
9640: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
9650: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
9660: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
9670: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
9680: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
9690: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
96a0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
96b0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
96c0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
96d0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
96e0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
96f0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
9700: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
9710: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
9720: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9730: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9740: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
9750: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
9760: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
9770: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
9780: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9790: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
97a0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
97b0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
97c0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
97d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
97e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
97f0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
9800: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
9810: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
9820: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
9830: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
9840: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
9850: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
9860: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9870: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
9880: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
9890: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
98a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
98b0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
98c0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
98d0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
98e0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
98f0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
9900: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
9910: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
9920: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
9930: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
9940: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
9950: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
9960: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
9970: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
9980: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
9990: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
99a0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
99b0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
99c0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
99d0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
99e0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
99f0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
9a00: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
9a10: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
9a20: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
9a30: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
9a40: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
9a50: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
9a60: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
9a70: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
9a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
9a90: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
9aa0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
9ab0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
9ac0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
9ad0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
9ae0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
9af0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
9b00: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
9b10: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
9b20: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
9b30: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
9b40: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
9b50: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
9b60: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
9b70: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
9b80: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
9b90: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
9ba0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
9bb0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
9bc0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
9bd0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
9be0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9bf0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
9c00: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
9c10: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
9c20: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
9c30: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
9c40: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
9c50: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
9c60: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
9c70: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
9c80: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
9c90: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
9ca0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
9cb0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
9cc0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
9cd0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
9ce0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
9cf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
9d00: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
9d10: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
9d20: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
9d30: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
9d40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
9d50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
9d60: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
9d70: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
9d80: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
9d90: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
9da0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
9db0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
9dc0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
9dd0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
9de0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
9df0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
9e00: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
9e10: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
9e20: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
9e30: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
9e40: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
9e50: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
9e60: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
9e70: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
9e80: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
9e90: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
9ea0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
9eb0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
9ec0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
9ed0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
9ee0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
9ef0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
9f00: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
9f10: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
9f20: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
9f30: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
9f40: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
9f50: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
9f60: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
9f70: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
9f80: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
9f90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9fa0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
9fb0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
9fc0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
9fd0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
9fe0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
9ff0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
a000: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
a010: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
a020: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
a030: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
a040: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
a050: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
a060: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
a070: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
a080: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
a090: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
a0a0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
a0b0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
a0c0: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
a0d0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
a0e0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
a0f0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
a100: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
a110: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
a120: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
a130: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
a140: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
a150: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
a160: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
a170: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
a180: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
a190: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
a1a0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
a1b0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
a1c0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
a1d0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
a1e0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
a1f0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
a200: 65 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20  er multipled by 
a210: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
a220: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
a230: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
a240: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
a250: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
a260: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
a270: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
a280: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
a290: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
a2a0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
a2b0: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
a2c0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
a2d0: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
a2e0: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
a2f0: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
a300: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
a310: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
a320: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
a330: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
a340: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
a350: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
a360: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
a370: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
a380: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
a390: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
a3a0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
a3b0: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
a3c0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
a3d0: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
a3e0: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
a3f0: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
a400: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
a410: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
a420: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
a430: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
a440: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
a450: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
a460: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
a470: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
a480: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
a490: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
a4a0: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
a4b0: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
a4c0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
a4d0: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
a4e0: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
a4f0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
a500: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
a510: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
a520: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
a530: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
a540: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
a550: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
a560: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
a570: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
a580: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
a590: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
a5a0: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
a5b0: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
a5c0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
a5d0: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
a5e0: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
a5f0: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
a600: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
a610: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
a620: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
a630: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
a640: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
a650: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
a660: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
a670: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
a680: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
a690: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
a6a0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
a6b0: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
a6c0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
a6d0: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
a6e0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
a6f0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
a700: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
a710: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
a720: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
a730: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
a740: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
a750: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
a760: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
a770: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
a780: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
a790: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
a7a0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
a7b0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
a7c0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
a7d0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
a7e0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
a7f0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
a800: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
a810: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
a820: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
a830: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
a840: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
a850: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
a860: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
a870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
a880: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a890: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
a8a0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
a8b0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
a8c0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
a8d0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
a8e0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
a8f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a900: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
a910: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
a920: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
a930: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a940: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
a950: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
a960: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
a970: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
a980: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a990: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a9a0: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
a9b0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
a9c0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
a9d0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
a9e0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
a9f0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
aa00: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
aa10: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
aa20: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
aa30: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
aa40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
aa50: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
aa60: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
aa70: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
aa80: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
aa90: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
aaa0: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
aab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
aac0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
aad0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
aae0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
aaf0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
ab00: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
ab10: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
ab20: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
ab30: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
ab40: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
ab50: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
ab60: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
ab70: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ab80: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ab90: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
aba0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
abb0: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
abc0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
abd0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
abe0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
abf0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
ac00: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
ac10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
ac20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
ac30: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
ac40: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
ac50: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
ac60: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
ac70: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
ac80: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
ac90: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
aca0: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
acb0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
acc0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
acd0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ace0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
acf0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
ad00: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
ad10: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
ad20: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ad30: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ad40: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
ad50: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
ad60: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
ad70: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ad80: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
ad90: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ada0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
adb0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
adc0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
add0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ade0: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
adf0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
ae00: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
ae10: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
ae20: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
ae30: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
ae40: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
ae50: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
ae60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
ae70: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
ae80: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
ae90: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
aea0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
aeb0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
aec0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
aed0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
aee0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
aef0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
af00: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
af10: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
af20: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
af30: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
af40: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
af50: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
af60: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
af70: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
af80: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
af90: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
afa0: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
afb0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
afc0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
afd0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
afe0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
aff0: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
b000: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
b010: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
b020: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
b030: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
b040: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
b050: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
b060: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
b070: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
b080: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
b090: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
b0a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
b0b0: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
b0c0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
b0d0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
b0e0: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
b0f0: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
b100: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
b110: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
b120: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
b130: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
b140: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
b150: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
b160: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
b170: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
b180: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b190: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
b1a0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
b1b0: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
b1c0: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
b1d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
b1e0: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
b1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b200: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
b210: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
b220: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
b230: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
b240: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
b250: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
b260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b270: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
b280: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
b290: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
b2a0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
b2b0: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
b2c0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
b2d0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
b2e0: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
b2f0: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
b300: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
b310: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
b320: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
b330: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b340: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
b350: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
b360: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
b370: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
b380: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
b390: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
b3a0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
b3b0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
b3c0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
b3d0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
b3e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
b3f0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
b400: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
b410: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
b420: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
b430: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b440: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
b450: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
b460: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
b470: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
b480: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
b490: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
b4a0: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
b4b0: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
b4c0: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
b4d0: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
b4e0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
b4f0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
b500: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
b510: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
b520: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
b530: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
b540: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
b550: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
b560: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
b570: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
b580: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
b590: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
b5a0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
b5b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
b5c0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b5d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
b5e0: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
b5f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
b600: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
b610: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b620: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
b630: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
b640: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b650: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
b660: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
b670: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
b680: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
b690: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
b6a0: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
b6b0: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
b6c0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
b6d0: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
b6e0: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
b6f0: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
b700: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
b710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b720: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
b730: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
b740: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
b750: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
b760: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
b770: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b780: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
b790: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
b7a0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
b7b0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
b7c0: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
b7d0: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
b7e0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
b7f0: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
b800: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
b810: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
b820: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
b830: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
b840: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
b850: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
b860: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
b870: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
b880: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
b890: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
b8a0: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
b8b0: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
b8c0: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
b8d0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
b8e0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
b8f0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
b900: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
b910: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
b920: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
b930: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
b940: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b950: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
b960: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
b970: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
b980: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
b990: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
b9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9b0: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
b9c0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
b9d0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b9e0: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
b9f0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
ba00: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
ba10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
ba20: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
ba30: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
ba40: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
ba50: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
ba60: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ba70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ba80: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ba90: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
baa0: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
bab0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
bac0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
bad0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
bae0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
baf0: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
bb00: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
bb10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bb20: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
bb30: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
bb40: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
bb50: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
bb60: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
bb70: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
bb80: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
bb90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bba0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbb0: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
bbc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bbd0: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
bbe0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
bbf0: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
bc00: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
bc10: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
bc20: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
bc30: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
bc40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
bc50: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
bc60: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
bc70: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
bc80: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
bc90: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
bca0: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
bcb0: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
bcc0: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
bcd0: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
bce0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
bcf0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
bd00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
bd10: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
bd20: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
bd30: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
bd40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
bd50: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
bd60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
bd70: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
bd80: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
bd90: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
bda0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
bdb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bdc0: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
bdd0: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
bde0: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
bdf0: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
be00: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
be10: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
be20: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
be30: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
be40: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
be50: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
be60: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
be70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
be80: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
be90: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
bea0: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
beb0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
bec0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
bed0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
bee0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
bef0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
bf00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bf10: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
bf20: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
bf30: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
bf40: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
bf50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
bf60: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
bf70: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
bf80: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
bf90: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
bfa0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
bfb0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
bfc0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
bfd0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
bfe0: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
bff0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
c000: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
c010: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
c020: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
c030: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
c040: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
c050: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
c060: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
c070: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
c080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
c090: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
c0a0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
c0b0: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
c0c0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
c0d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
c0e0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
c0f0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
c100: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
c110: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
c120: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
c130: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c140: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
c150: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
c160: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
c170: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
c180: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
c190: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
c1a0: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
c1b0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
c1c0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
c1d0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
c1e0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
c1f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
c200: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
c210: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
c220: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
c230: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
c240: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
c250: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
c260: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c270: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
c280: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
c290: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
c2a0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
c2b0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
c2c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
c2d0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
c2e0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
c2f0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
c300: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
c310: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
c320: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
c330: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
c340: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
c350: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
c360: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
c370: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
c380: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
c390: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
c3a0: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
c3b0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
c3c0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
c3d0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
c3e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
c3f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
c400: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
c410: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
c420: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
c430: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
c440: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
c450: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
c460: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
c470: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c480: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
c490: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
c4a0: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
c4b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
c4c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
c4d0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
c4e0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
c4f0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
c500: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c510: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
c520: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
c530: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
c540: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
c550: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
c560: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
c570: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c580: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
c590: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
c5a0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
c5b0: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
c5c0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
c5d0: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
c5e0: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
c5f0: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
c600: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
c610: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
c620: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
c630: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
c640: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
c650: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
c660: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
c670: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
c680: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
c690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
c6a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
c6b0: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
c6c0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
c6d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
c6e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c6f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
c700: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
c710: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
c720: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
c730: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
c740: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
c750: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
c760: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c770: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
c780: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c790: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
c7a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
c7b0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
c7c0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
c7d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
c7e0: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
c7f0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
c800: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
c810: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
c820: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
c830: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
c840: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
c850: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
c860: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
c870: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
c880: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
c890: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
c8a0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
c8b0: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
c8c0: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
c8d0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
c8e0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
c8f0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
c900: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
c910: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
c920: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
c930: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
c940: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
c950: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
c960: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c970: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
c980: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
c990: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
c9a0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
c9b0: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
c9c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
c9d0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
c9e0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
c9f0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
ca00: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
ca10: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
ca20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
ca30: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
ca40: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
ca50: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
ca60: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
ca70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ca80: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
ca90: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
caa0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
cab0: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
cac0: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
cad0: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
cae0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
caf0: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
cb00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cb10: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
cb20: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
cb30: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
cb40: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
cb50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
cb60: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
cb70: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
cb80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
cb90: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
cba0: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
cbb0: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
cbc0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
cbd0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
cbe0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
cbf0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
cc00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cc10: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
cc20: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
cc30: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
cc40: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
cc50: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
cc60: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
cc70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
cc80: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
cc90: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
cca0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ccb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
ccc0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ccd0: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
cce0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
ccf0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
cd00: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
cd10: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
cd20: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
cd30: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
cd40: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
cd50: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
cd60: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
cd70: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
cd80: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
cd90: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
cda0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
cdb0: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
cdc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
cdd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
cde0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
cdf0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
ce00: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
ce10: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
ce20: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
ce30: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
ce40: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
ce50: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
ce60: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
ce70: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
ce80: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
ce90: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
cea0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ceb0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
cec0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ced0: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
cee0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
cef0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
cf00: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
cf10: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
cf20: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
cf30: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
cf40: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
cf50: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
cf60: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
cf70: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
cf80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cf90: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
cfa0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
cfb0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
cfc0: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
cfd0: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
cfe0: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
cff0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
d000: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
d010: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
d020: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
d030: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
d040: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
d050: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
d060: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
d070: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
d080: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
d090: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
d0a0: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
d0b0: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
d0c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
d0d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
d0e0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
d0f0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
d100: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
d110: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d120: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
d130: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
d140: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
d150: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
d160: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
d170: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
d180: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
d190: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
d1a0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
d1b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
d1c0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
d1d0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
d1e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
d1f0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
d200: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
d210: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
d220: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
d230: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
d240: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
d250: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
d260: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
d270: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
d280: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
d290: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
d2a0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
d2b0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
d2c0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
d2d0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
d2e0: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
d2f0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
d300: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
d310: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
d320: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
d330: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
d340: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
d350: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
d360: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
d370: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
d380: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
d390: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
d3a0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
d3b0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
d3c0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
d3d0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
d3e0: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
d3f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
d400: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
d410: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d420: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
d430: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
d440: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
d450: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
d460: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
d470: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
d480: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
d490: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
d4a0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
d4b0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
d4c0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
d4d0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
d4e0: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
d4f0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
d500: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
d510: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
d520: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
d530: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
d540: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
d550: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
d560: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
d570: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
d580: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
d590: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
d5a0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
d5b0: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
d5c0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
d5d0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
d5e0: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
d5f0: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
d600: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d610: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
d620: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
d630: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
d640: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
d650: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
d660: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
d670: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
d680: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d690: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
d6a0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
d6b0: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
d6c0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
d6d0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
d6e0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
d6f0: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
d700: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
d710: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
d720: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
d730: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
d740: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
d750: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
d760: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
d770: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
d780: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
d790: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
d7a0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
d7b0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
d7c0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
d7d0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
d7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
d7f0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
d800: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
d810: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
d820: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d830: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
d840: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
d850: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
d860: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
d870: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
d880: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
d890: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
d8a0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
d8b0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
d8c0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d8d0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
d8e0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
d8f0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
d900: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d910: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
d920: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
d930: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
d940: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
d950: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
d960: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d970: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
d980: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
d990: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
d9a0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
d9b0: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
d9c0: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
d9d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
d9e0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d9f0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
da00: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
da10: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
da20: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
da30: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
da40: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
da50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
da60: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
da70: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
da80: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
da90: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
daa0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
dab0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
dac0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
dad0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
dae0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
daf0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
db00: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
db10: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
db20: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
db30: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
db40: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
db50: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
db60: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
db70: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
db80: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
db90: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
dba0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
dbb0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
dbc0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
dbd0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
dbe0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
dbf0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
dc00: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
dc10: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
dc20: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
dc30: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
dc40: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
dc50: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
dc60: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
dc70: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
dc80: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
dc90: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
dca0: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
dcb0: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
dcc0: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
dcd0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
dce0: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
dcf0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
dd00: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
dd10: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
dd20: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
dd30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
dd40: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
dd50: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
dd60: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
dd70: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
dd80: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
dd90: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
dda0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
ddb0: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
ddc0: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
ddd0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
dde0: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
ddf0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
de00: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
de10: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
de20: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
de30: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
de40: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
de50: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
de60: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
de70: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
de80: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
de90: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
dea0: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
deb0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
dec0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
ded0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
dee0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
def0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
df00: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
df10: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
df20: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
df30: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
df40: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
df50: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
df60: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
df70: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
df80: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
df90: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
dfa0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
dfb0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
dfc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
dfd0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
dfe0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
dff0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
e000: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
e010: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
e020: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
e030: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
e040: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
e050: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
e060: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
e070: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
e080: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
e090: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
e0a0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
e0b0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
e0c0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
e0d0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
e0e0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
e0f0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
e100: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
e110: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
e120: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
e130: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
e140: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e150: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
e160: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
e170: 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
e180: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
e190: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
e1a0: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
e1b0: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
e1c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e1d0: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
e1e0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
e1f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e200: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
e210: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
e220: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
e230: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e240: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
e250: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
e260: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
e270: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
e280: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e290: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
e2a0: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
e2b0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
e2c0: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
e2d0: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
e2e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e2f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
e300: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
e310: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
e320: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
e330: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
e340: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
e350: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
e360: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
e370: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
e380: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e390: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
e3a0: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
e3b0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
e3c0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
e3d0: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
e3e0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
e3f0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
e400: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
e410: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
e420: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
e430: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
e440: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
e450: 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
e460: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e470: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e480: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
e490: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
e4a0: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
e4b0: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
e4c0: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
e4d0: 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
e4e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
e4f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
e500: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
e510: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
e520: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
e530: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
e540: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
e550: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
e560: 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
e570: 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
e580: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
e590: 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
e5a0: 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
e5b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
e5c0: 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
e5d0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e5e0: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
e5f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
e600: 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
e610: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e620: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
e630: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e640: 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
e650: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e660: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
e670: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
e680: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
e690: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
e6a0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
e6b0: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
e6c0: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
e6d0: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e6e0: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e6f0: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
e700: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
e710: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
e720: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e730: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
e740: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e750: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
e760: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
e770: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
e780: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e790: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e7a0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
e7b0: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
e7c0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
e7d0: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
e7e0: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
e7f0: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
e800: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
e810: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
e820: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
e830: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
e840: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
e850: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e860: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
e870: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
e880: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e890: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e8a0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e8b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e8c0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e8d0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e8e0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e8f0: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
e900: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
e910: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
e920: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e930: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
e940: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
e950: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
e960: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
e970: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
e980: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e990: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
e9a0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
e9b0: 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
e9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
e9d0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
e9e0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
e9f0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
ea00: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
ea10: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ea20: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
ea30: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
ea40: 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
ea50: 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
ea60: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
ea70: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
ea80: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
ea90: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
eaa0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
eab0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
eac0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
ead0: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
eae0: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
eaf0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
eb00: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
eb10: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
eb20: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
eb30: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
eb40: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
eb50: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
eb60: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
eb70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
eb80: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
eb90: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
eba0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
ebb0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
ebc0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
ebd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ebe0: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
ebf0: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
ec00: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
ec10: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
ec20: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
ec30: 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
ec40: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ec50: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ec60: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ec70: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ec80: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ec90: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
eca0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
ecb0: 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
ecc0: 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
ecd0: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
ece0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
ecf0: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
ed00: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
ed10: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
ed20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
ed30: 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
ed40: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
ed50: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
ed60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
ed70: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
ed80: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
ed90: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
eda0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
edb0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
edc0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
edd0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
ede0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
edf0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
ee00: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ee10: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
ee20: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ee30: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
ee40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ee50: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
ee60: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
ee70: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
ee80: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
ee90: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
eea0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
eeb0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
eec0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
eed0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
eee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
eef0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
ef00: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
ef10: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ef20: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
ef30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
ef40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ef50: 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
ef60: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
ef70: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
ef80: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ef90: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
efa0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
efb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
efc0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
efd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
efe0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
eff0: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
f000: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
f010: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
f020: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
f030: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
f040: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f050: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
f060: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
f070: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
f080: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
f090: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
f0a0: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
f0b0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
f0c0: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
f0d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f0e0: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
f0f0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
f100: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
f110: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
f120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f130: 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
f140: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
f150: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
f160: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f170: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
f180: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
f190: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
f1a0: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
f1b0: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
f1c0: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
f1d0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
f1e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
f1f0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
f200: 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
f210: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
f220: 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
f230: 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
f240: 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
f250: 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
f260: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
f270: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
f280: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
f290: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
f2a0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
f2b0: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
f2c0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f2d0: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
f2e0: 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
f2f0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
f300: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
f310: 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
f320: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
f330: 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
f340: 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
f350: 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
f360: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f370: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
f380: 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
f390: 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
f3a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
f3b0: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
f3c0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
f3d0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
f3e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
f3f0: 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
f400: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f410: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
f420: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f430: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f440: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f450: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f460: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
f470: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
f480: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
f490: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
f4a0: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
f4b0: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
f4c0: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
f4d0: 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
f4e0: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
f4f0: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
f500: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
f510: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
f520: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
f530: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
f540: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
f550: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
f560: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
f570: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
f580: 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
f590: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
f5a0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
f5b0: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
f5c0: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
f5d0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
f5e0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
f5f0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f600: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
f610: 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
f620: 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
f630: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
f640: 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
f650: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
f660: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
f670: 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
f680: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
f690: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
f6a0: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
f6b0: 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
f6c0: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
f6d0: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
f6e0: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
f6f0: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
f700: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
f710: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
f720: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
f730: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f740: 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
f750: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f760: 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
f770: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
f780: 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
f790: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f7a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
f7b0: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f7c0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
f7d0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
f7e0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
f7f0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
f800: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
f810: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
f820: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
f830: 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
f840: 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
f850: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
f860: 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  nation.  .** Thi
f870: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
f880: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
f890: 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
f8a0: 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
f8b0: 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
f8c0: 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
f8d0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
f8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f8f0: 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  E option..** The
f900: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
f910: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f920: 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
f930: 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
f940: 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
f950: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
f960: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
f970: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
f980: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
f990: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
f9a0: 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
f9b0: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
f9c0: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
f9d0: 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
f9e0: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
f9f0: 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
fa00: 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
fa10: 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
fa20: 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
fa30: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
fa40: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
fa50: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
fa60: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
fa70: 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
fa80: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
fa90: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
faa0: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
fab0: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
fac0: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
fad0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
fae0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
faf0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
fb00: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
fb10: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
fb20: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
fb30: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
fb40: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
fb50: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
fb60: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
fb70: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
fb80: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
fb90: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
fba0: 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
fbb0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
fbc0: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
fbd0: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
fbe0: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
fbf0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
fc00: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
fc10: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
fc20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
fc30: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
fc40: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
fc50: 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
fc60: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
fc70: 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
fc80: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
fc90: 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
fca0: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
fcb0: 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
fcc0: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
fcd0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
fce0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
fcf0: 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
fd00: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
fd10: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
fd20: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
fd30: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
fd40: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
fd50: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
fd60: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
fd70: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
fd80: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
fd90: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
fda0: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
fdb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
fdc0: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
fdd0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
fde0: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
fdf0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
fe00: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
fe10: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
fe20: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
fe30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
fe40: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
fe50: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
fe60: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
fe70: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
fe80: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
fe90: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
fea0: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
feb0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
fec0: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
fed0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
fee0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
fef0: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
ff00: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
ff10: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
ff20: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
ff30: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
ff40: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
ff50: 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
ff60: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
ff70: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
ff80: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
ff90: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
ffa0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
ffb0: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
ffc0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
ffd0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
ffe0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
fff0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
10000 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
10010 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10020 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
10030 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
10040 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
10050 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
10060 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
10070 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
10080 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
10090 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
100a0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
100b0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
100c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
100d0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31  is capped at 2^1
100e0 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
100f0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
10100 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
10110 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20  on size are 2^5 
10120 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64  through 2^8.</dd
10130 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10140 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
10150 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10160 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
10170 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10180 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10190 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
101a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
101b0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
101c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
101d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
101e0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
101f0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
10200 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
10210 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
10220 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10230 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
10240 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
10250 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
10260 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
10270 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
10280 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
10290 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
102a0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
102b0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
102c0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
102d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
102e0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
102f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10300 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
10310 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10320 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
10330 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
10340 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10350 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
10360 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
10370 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10380 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10390 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
103a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
103b0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
103c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
103d0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
103e0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
103f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10400 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10410 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10420 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
10430 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
10440 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
10450 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10460 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10470 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10480 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10490 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
104a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
104b0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
104c0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
104d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
104e0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
104f0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
10500 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
10510 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
10520 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
10530 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
10540 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
10550 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
10560 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
10570 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
10580 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
10590 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
105a0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
105b0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
105c0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
105d0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
105e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
105f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10600 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10610 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10620 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10630 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10640 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
10650 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
10660 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
10670 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
10680 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
10690 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
106a0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
106b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
106c0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
106d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
106e0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
106f0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
10700 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10710 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
10720 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
10730 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
10740 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10750 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10760 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
10770 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
10780 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
10790 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
107a0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
107b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
107c0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
107d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
107e0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
107f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
10800 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
10810 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
10820 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
10830 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
10840 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
10850 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
10860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10870 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
10880 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10890 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
108a0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
108b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
108c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
108d0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
108e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
108f0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
10900 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
10910 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
10920 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
10930 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
10940 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
10950 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10960 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  PCACHE]] <dt>SQL
10970 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
10980 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10990 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
109a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
109b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
109c0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
109d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
109e0 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
109f0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
10a00 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
10a10 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
10a20 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
10a30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
10a40 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
10a50 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
10a60 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
10a70 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
10a80 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
10a90 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
10aa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10ab0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 20  FIG_GETPCACHE]] 
10ac0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10ad0 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e  G_GETPCACHE</dt>
10ae0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10af0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
10b00 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
10b10 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
10b20 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
10b30 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
10b40 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
10b50 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
10b60 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
10b70 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
10b80 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
10b90 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
10ba0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10bb0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
10bc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
10bd0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
10be0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
10bf0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
10c00 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
10c10 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
10c20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
10c30 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
10c40 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
10c50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
10c60 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
10c70 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
10c80 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
10c90 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
10ca0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
10cb0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
10cc0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
10cd0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
10ce0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
10cf0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
10d00 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
10d10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
10d20 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
10d30 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
10d40 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
10d50 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
10d60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10d70 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
10d80 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
10d90 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
10da0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10db0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
10dc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
10dd0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
10de0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
10df0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
10e00 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
10e10 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10e20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10e30 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
10e40 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10e50 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
10e60 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
10e70 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
10e80 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
10e90 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
10ea0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
10eb0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10ec0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
10ed0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
10ee0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
10ef0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
10f00 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
10f10 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
10f20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
10f30 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
10f40 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
10f50 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
10f60 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
10f70 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
10f80 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
10f90 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
10fa0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
10fb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
10fc0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10fd0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
10fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10ff0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
11000 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
11010 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
11020 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11030 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
11040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11050 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
11060 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11070 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11080 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
11090 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
110a0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
110b0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
110c0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
110d0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
110e0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
110f0 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
11100 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
11110 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
11120 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
11130 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
11140 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
11150 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
11160 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
11170 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
11180 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
11190 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
111a0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
111b0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
111c0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
111d0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
111e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
111f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
11200 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
11210 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
11220 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
11230 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
11240 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
11250 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
11260 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
11270 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
11280 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
11290 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
112a0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
112b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
112c0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
112d0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
112e0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
112f0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
11300 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
11310 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
11320 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
11330 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
11340 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
11350 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f 64   defined..** </d
11360 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
11370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11380 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
11390 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
113a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
113b0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
113c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
113d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
113e0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
113f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
11400 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11410 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
11420 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
11430 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11450 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
11460 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
11470 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
11480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11490 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
114a0 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
114b0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
114c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
114d0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
114e0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
114f0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
11500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11510 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
11520 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
11530 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
11540 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
11550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11560 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
11570 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
11580 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11590 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
115a0 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
115b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
115c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
115d0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
115e0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
115f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11600 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
11610 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
11620 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
11630 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
11640 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
11650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11660 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
11670 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
11680 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11690 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
116a0 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
116b0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
116c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
116d0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
116e0 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
116f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
11700 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
11710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
11720 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
11730 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
11740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11750 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
11760 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
11770 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
11780 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
11790 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
117a0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
117b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
117c0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
117d0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
117e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
117f0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11800 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11810 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11820 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11830 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
11840 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11850 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11860 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11870 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
11880 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
11890 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
118a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
118b0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
118c0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
118d0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
118e0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
118f0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
11900 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11910 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
11920 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
11930 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
11940 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11950 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11960 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11970 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11980 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11990 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
119a0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
119b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
119c0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
119d0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
119e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
119f0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
11a00 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
11a10 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
11a20 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
11a30 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
11a40 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
11a50 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
11a60 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
11a70 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
11a80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11a90 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
11aa0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
11ab0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
11ac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11ad0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
11ae0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
11af0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
11b00 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
11b10 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
11b20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11b30 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
11b40 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11b50 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
11b60 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
11b70 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
11b80 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
11b90 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
11ba0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
11bb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11bc0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
11bd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
11be0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
11bf0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
11c00 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
11c10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
11c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
11c30 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
11c40 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
11c50 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11c60 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
11c70 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
11c80 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
11c90 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
11ca0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
11cb0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
11cc0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
11cd0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11ce0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
11cf0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
11d00 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
11d10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11d20 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
11d30 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
11d40 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
11d50 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
11d60 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
11d70 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
11d80 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
11d90 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
11da0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
11db0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
11dc0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
11dd0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
11de0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
11df0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
11e00 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
11e10 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
11e20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
11e30 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
11e40 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
11e50 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
11e60 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
11e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11e80 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
11e90 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
11ea0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
11eb0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
11ec0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
11ed0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
11ee0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
11ef0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
11f00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11f10 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
11f20 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
11f30 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
11f40 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
11f50 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
11f60 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
11f70 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
11f80 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
11f90 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
11fa0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
11fb0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
11fc0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
11fd0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
11fe0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
11ff0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
12000 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
12010 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
12020 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
12030 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12040 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
12050 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
12060 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
12070 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
12080 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
12090 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
120a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
120b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
120c0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
120d0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
120e0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
120f0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
12100 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
12110 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
12120 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
12130 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
12140 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
12150 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
12160 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
12170 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
12180 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
12190 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
121a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
121b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
121c0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
121d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
121e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
121f0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
12200 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
12210 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
12220 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
12230 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
12240 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
12250 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12260 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
12270 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
12280 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
12290 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
122a0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
122b0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
122c0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
122d0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
122e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
122f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
12300 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
12310 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
12320 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
12330 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
12340 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
12350 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
12360 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
12370 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
12380 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12390 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
123a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
123b0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
123c0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
123d0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
123e0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
123f0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
12400 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
12410 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
12420 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
12430 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
12440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
12450 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
12460 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
12470 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
12480 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
12490 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
124a0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
124b0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
124c0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
124d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
124e0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
124f0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
12500 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
12510 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
12520 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
12530 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
12540 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
12550 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
12560 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
12570 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
12580 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
12590 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
125a0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
125b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
125c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
125d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
125e0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
125f0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
12600 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
12610 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
12620 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
12630 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
12640 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
12650 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
12660 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
12670 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
12680 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
12690 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
126a0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
126b0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
126c0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
126d0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
126e0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
126f0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
12700 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
12710 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
12720 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
12730 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
12740 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
12750 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
12760 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
12770 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
12780 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
12790 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
127a0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
127b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
127c0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
127d0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
127e0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
127f0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
12800 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
12810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12820 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
12830 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20   argument.  ^As 
12840 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
12850 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f  n 3.7.7, this ro
12860 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64  utines.** record
12870 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
12880 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20  t rowid of both 
12890 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20  ordinary tables 
128a0 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62  and [virtual tab
128b0 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  les]..** ^If no 
128c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
128d0 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
128e0 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
128f0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
12900 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
12910 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
12920 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
12930 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
12940 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
12950 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
12960 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
12970 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
12980 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
12990 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
129a0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
129b0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
129c0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
129d0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
129e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
129f0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
12a00 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
12a10 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
12a20 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
12a30 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
12a40 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
12a50 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
12a60 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
12a70 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
12a80 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
12a90 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
12aa0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
12ab0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
12ac0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
12ad0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
12ae0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
12af0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
12b00 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
12b10 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
12b20 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
12b30 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
12b40 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
12b50 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
12b60 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
12b70 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
12b80 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
12b90 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
12ba0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
12bb0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
12bc0 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
12bd0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
12be0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
12bf0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
12c00 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
12c10 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
12c20 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
12c30 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
12c40 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
12c50 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
12c60 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
12c70 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
12c80 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
12c90 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
12ca0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
12cb0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
12cc0 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
12cd0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
12ce0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
12cf0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
12d00 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
12d10 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
12d20 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
12d30 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
12d40 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
12d50 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
12d60 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
12d70 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
12d80 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
12d90 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
12da0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
12db0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
12dc0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
12dd0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
12de0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
12df0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
12e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12e10 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
12e20 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
12e30 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
12e40 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
12e50 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
12e60 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
12e70 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
12e80 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
12e90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
12ea0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
12eb0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
12ec0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
12ed0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
12ee0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
12ef0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
12f00 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
12f10 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
12f20 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
12f30 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
12f40 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
12f50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
12f60 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
12f70 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
12f80 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
12f90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
12fa0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
12fb0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
12fc0 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
12fd0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
12fe0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
12ff0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
13000 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
13010 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13020 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
13030 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
13040 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
13050 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
13060 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
13070 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
13080 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
13090 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
130a0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
130b0 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
130c0 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
130d0 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
130e0 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
130f0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
13100 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
13110 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
13120 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
13130 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
13140 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
13150 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
13160 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
13170 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
13180 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
13190 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
131a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
131b0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
131c0 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
131d0 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
131e0 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
131f0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
13200 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
13210 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
13220 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
13230 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
13240 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
13250 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
13260 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
13270 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
13280 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
13290 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
132a0 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
132b0 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
132c0 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
132d0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
132e0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
132f0 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
13300 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
13310 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
13320 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
13330 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
13340 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
13350 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
13360 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
13370 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
13380 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
13390 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
133a0 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
133b0 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
133c0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
133d0 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
133e0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
133f0 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
13400 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
13410 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
13420 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
13430 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
13440 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
13450 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
13460 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
13470 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
13480 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
13490 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
134a0 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
134b0 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
134c0 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
134d0 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
134e0 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
134f0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
13500 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
13510 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
13520 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
13530 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
13540 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
13550 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
13560 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
13570 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
13580 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
13590 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
135a0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
135b0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
135c0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
135d0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
135e0 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
135f0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
13600 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
13610 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
13620 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
13630 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
13640 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
13650 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
13660 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
13670 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
13680 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
13690 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
136a0 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
136b0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
136c0 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
136d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
136e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
136f0 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
13700 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13710 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
13720 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
13730 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
13740 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
13750 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
13760 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
13770 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
13780 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
13790 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
137a0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
137b0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
137c0 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
137d0 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
137e0 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
137f0 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
13800 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
13810 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
13820 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
13830 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
13840 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
13850 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
13860 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
13870 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
13880 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
13890 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
138a0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
138b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
138c0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
138d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
138e0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
138f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
13900 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
13910 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
13920 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
13930 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
13940 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
13950 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
13960 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
13970 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
13980 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
13990 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
139a0 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
139b0 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
139c0 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
139d0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
139e0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
139f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13a00 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
13a10 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
13a20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
13a30 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
13a40 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
13a50 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
13a60 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
13a70 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
13a80 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
13a90 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
13aa0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
13ab0 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
13ac0 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
13ad0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
13ae0 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
13af0 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
13b00 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
13b10 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
13b20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
13b30 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
13b40 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
13b50 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
13b60 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
13b70 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
13b80 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
13b90 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
13ba0 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
13bb0 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
13bc0 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
13bd0 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
13be0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
13bf0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
13c00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
13c10 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
13c20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
13c30 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
13c40 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
13c50 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
13c60 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
13c70 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
13c80 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
13c90 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
13ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
13cb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
13cc0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
13cd0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
13ce0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
13cf0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
13d00 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
13d10 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
13d20 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
13d30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
13d40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13d50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13d60 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
13d70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
13d80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
13d90 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
13da0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
13db0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
13dc0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
13dd0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
13de0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
13df0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
13e00 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
13e10 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
13e20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13e30 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
13e40 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
13e50 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
13e60 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
13e70 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
13e80 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
13e90 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
13ea0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
13eb0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
13ec0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
13ed0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
13ee0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
13ef0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
13f00 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
13f10 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
13f20 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
13f30 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
13f40 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
13f50 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
13f60 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
13f70 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
13f80 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
13f90 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
13fa0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
13fb0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
13fc0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
13fd0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
13fe0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
13ff0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
14000 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
14010 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
14020 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
14030 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
14040 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
14050 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
14060 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
14070 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
14080 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
14090 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
140a0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
140b0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
140c0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
140d0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
140e0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
140f0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
14100 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
14110 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
14120 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
14130 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
14140 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
14150 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
14160 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
14170 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
14180 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
14190 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
141a0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
141b0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
141c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
141d0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
141e0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
141f0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
14200 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
14210 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
14220 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
14230 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
14240 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
14250 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
14260 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
14270 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
14280 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
14290 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
142a0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
142b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
142c0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
142d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
142e0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
142f0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
14300 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14310 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
14320 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
14330 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
14340 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
14350 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
14360 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
14370 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
14380 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
14390 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
143a0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
143b0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
143c0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
143d0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
143e0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
143f0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
14400 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
14410 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14420 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
14430 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
14440 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
14450 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
14460 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
14470 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
14480 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
14490 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
144a0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
144b0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
144c0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
144d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
144e0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
144f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
14500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14510 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
14520 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
14530 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
14540 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
14550 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
14560 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
14570 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14580 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
14590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
145a0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
145b0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
145c0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
145d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
145e0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
145f0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
14600 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
14610 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
14620 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
14630 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
14640 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
14650 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
14660 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
14670 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
14680 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
14690 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
146a0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
146b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
146c0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
146d0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
146e0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
146f0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
14700 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
14710 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
14720 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
14730 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
14740 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
14750 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
14760 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
14770 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
14780 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
14790 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
147a0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
147b0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
147c0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
147d0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
147e0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
147f0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
14800 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
14810 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
14820 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
14830 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
14840 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
14850 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
14860 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
14870 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
14880 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
14890 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
148a0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
148b0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
148c0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
148d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
148e0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
148f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
14900 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
14910 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14920 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
14930 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
14940 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
14950 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
14960 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
14970 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
14980 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
14990 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
149a0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
149b0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
149c0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
149d0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
149e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
149f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
14a00 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
14a10 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
14a20 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
14a30 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
14a40 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
14a50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
14a60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
14a70 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
14a80 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
14a90 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
14aa0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
14ab0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
14ac0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
14ad0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
14ae0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
14af0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
14b00 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
14b10 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
14b20 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
14b30 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
14b40 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
14b50 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
14b60 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
14b70 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14b80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
14b90 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
14ba0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14bb0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
14bc0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
14bd0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
14be0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
14bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
14c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
14c10 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
14c20 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
14c30 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
14c40 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
14c50 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
14c60 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
14c70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
14c80 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
14c90 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
14ca0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
14cb0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
14cc0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
14cd0 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
14ce0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
14cf0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
14d00 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
14d10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
14d20 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
14d30 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
14d40 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
14d50 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14d60 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
14d70 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
14d80 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
14d90 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
14da0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
14db0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
14dc0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
14dd0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
14de0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
14df0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
14e00 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
14e10 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
14e20 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
14e30 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
14e40 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
14e50 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
14e60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
14e70 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
14e80 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
14e90 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
14ea0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
14eb0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
14ec0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
14ed0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
14ee0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
14ef0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
14f00 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
14f10 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
14f20 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
14f30 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
14f40 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
14f50 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
14f60 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
14f70 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
14f80 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
14f90 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14fa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
14fb0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
14fc0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
14fd0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
14fe0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
14ff0 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
15000 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
15010 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
15020 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
15030 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
15040 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
15050 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
15060 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
15070 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
15080 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
15090 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
150a0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
150b0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
150c0 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
150d0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
150e0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
150f0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
15100 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
15110 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
15120 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
15130 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
15140 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
15150 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
15160 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
15170 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
15180 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
15190 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
151a0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
151b0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
151c0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
151d0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
151e0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
151f0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
15200 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
15210 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
15220 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
15230 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
15240 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
15250 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
15260 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
15270 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
15280 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
15290 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
152a0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
152b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
152c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
152d0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
152e0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
152f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
15300 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
15310 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
15320 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
15330 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
15340 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
15350 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
15360 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
15370 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
15380 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
15390 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
153a0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
153b0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
153c0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
153d0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
153e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
153f0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
15400 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
15410 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
15420 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
15430 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
15440 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
15450 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
15460 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
15470 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
15480 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
15490 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
154a0 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
154b0 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
154c0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
154d0 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
154e0 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
154f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
15500 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
15510 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
15520 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
15530 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
15540 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
15550 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
15560 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
15570 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
15580 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
15590 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
155a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
155b0 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
155c0 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
155d0 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
155e0 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
155f0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
15600 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
15610 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
15620 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
15630 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
15640 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
15650 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
15660 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
15670 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
15680 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
15690 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
156a0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
156b0 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
156c0 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
156d0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
156e0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
156f0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
15700 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
15710 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
15720 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
15730 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
15740 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
15750 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
15760 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
15770 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
15780 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
15790 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
157a0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
157b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
157c0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
157d0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
157e0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
157f0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
15800 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
15810 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
15820 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
15830 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
15840 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
15850 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
15860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
15870 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
15880 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
15890 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
158a0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
158b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
158c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
158d0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
158e0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
158f0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
15900 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
15910 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
15920 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
15930 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
15940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15950 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
15960 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
15970 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
15980 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
15990 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
159a0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
159b0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
159c0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
159d0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
159e0 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
159f0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
15a00 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
15a10 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
15a20 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
15a30 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
15a40 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
15a50 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
15a60 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
15a70 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
15a80 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
15a90 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
15aa0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
15ab0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
15ac0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
15ad0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
15ae0 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
15af0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
15b00 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
15b10 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
15b20 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
15b30 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
15b40 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
15b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
15b60 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
15b70 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
15b80 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
15b90 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
15ba0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
15bb0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
15bc0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
15bd0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
15be0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
15bf0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
15c00 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
15c10 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
15c20 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
15c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
15c40 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
15c50 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
15c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
15c70 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
15c80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
15c90 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
15ca0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
15cb0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
15cc0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
15cd0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
15ce0 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  red.)^.*/.int sq
15cf0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
15d00 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
15d10 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
15d20 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
15d30 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
15d40 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
15d50 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
15d60 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
15d70 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
15d80 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15d90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15da0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
15db0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
15dc0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
15dd0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
15de0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
15df0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
15e00 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
15e10 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
15e20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15e30 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
15e40 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
15e50 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
15e60 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
15e70 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
15e80 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
15e90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
15ea0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
15eb0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
15ec0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
15ed0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
15ee0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
15ef0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
15f00 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
15f10 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
15f20 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
15f30 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
15f40 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
15f50 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
15f60 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
15f70 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
15f80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
15f90 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
15fa0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
15fb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
15fc0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
15fd0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
15fe0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
15ff0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
16000 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
16010 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
16020 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
16030 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
16040 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
16050 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
16060 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
16070 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
16080 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
16090 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
160a0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
160b0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
160c0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
160d0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
160e0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
160f0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
16100 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
16110 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
16120 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
16130 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
16140 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
16150 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
16160 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
16170 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
16180 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
16190 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
161a0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
161b0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
161c0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
161d0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
161e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
161f0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
16200 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
16210 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
16220 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
16230 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
16240 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
16250 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16260 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16270 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
16280 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
16290 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
162a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
162b0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
162c0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
162d0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
162e0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
162f0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
16300 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16310 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
16320 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
16330 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
16340 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
16350 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
16360 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
16370 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
16380 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
16390 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
163a0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
163b0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
163c0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
163d0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
163e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
163f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
16400 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
16410 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
16420 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16430 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
16440 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16450 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
16460 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16470 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
16480 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
16490 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
164a0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
164b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
164c0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
164d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
164e0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
164f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16500 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
16510 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16520 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
16530 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
16540 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
16550 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
16560 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
16570 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
16580 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
16590 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
165a0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
165b0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
165c0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
165d0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
165e0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
165f0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
16600 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
16610 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
16620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
16630 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
16640 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
16650 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16660 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
16670 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
16680 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
16690 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
166a0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
166b0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
166c0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
166d0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
166e0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
166f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
16700 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
16710 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
16720 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
16730 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
16740 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
16750 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
16760 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
16770 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
16780 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
16790 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
167a0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
167b0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
167c0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
167d0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
167e0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
167f0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
16800 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
16810 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
16820 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
16830 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16840 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
16850 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
16860 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
16870 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
16880 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
16890 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
168a0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
168b0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
168c0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
168d0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
168e0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
168f0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
16900 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
16910 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
16920 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
16930 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
16940 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
16950 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
16960 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
16970 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
16980 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
16990 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
169a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
169b0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
169c0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
169d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
169e0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
169f0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
16a00 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
16a10 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
16a20 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
16a30 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
16a40 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
16a50 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
16a60 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
16a70 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
16a80 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
16a90 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
16aa0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
16ab0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
16ac0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
16ad0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
16ae0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
16af0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
16b00 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
16b10 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
16b20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
16b30 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
16b40 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
16b50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
16b60 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
16b70 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
16b80 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
16b90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
16ba0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
16bb0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
16bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
16bd0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
16be0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
16bf0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
16c00 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
16c10 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
16c20 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
16c30 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
16c40 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
16c50 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
16c60 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
16c70 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
16c80 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
16c90 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
16ca0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
16cb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
16cc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16cd0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
16ce0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
16cf0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
16d00 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
16d10 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
16d20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
16d30 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
16d40 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
16d50 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
16d60 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
16d70 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
16d80 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
16d90 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
16da0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
16db0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16dc0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
16dd0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
16de0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16df0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
16e00 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
16e10 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
16e20 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
16e30 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
16e40 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
16e50 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
16e60 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
16e70 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
16e80 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
16e90 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
16ea0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
16eb0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
16ec0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
16ed0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
16ee0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
16ef0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
16f00 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
16f10 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
16f20 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
16f30 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
16f40 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
16f50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
16f60 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
16f70 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
16f80 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
16f90 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
16fa0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
16fb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16fc0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
16fd0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
16fe0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
16ff0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
17000 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
17010 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
17020 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
17030 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
17040 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
17050 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
17060 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
17070 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
17080 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
17090 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
170a0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
170b0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
170c0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
170d0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
170e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
170f0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
17100 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
17110 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
17120 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
17130 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
17140 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
17150 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
17160 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
17170 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
17180 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
17190 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
171a0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
171b0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
171c0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
171d0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
171e0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
171f0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
17200 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
17210 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
17220 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
17230 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
17240 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
17250 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
17260 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
17270 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
17280 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
17290 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
172a0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
172b0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
172c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
172d0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
172e0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
172f0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
17300 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
17310 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
17320 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
17330 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
17340 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
17350 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
17360 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
17370 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
17380 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
17390 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
173a0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
173b0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
173c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
173d0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
173e0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
173f0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
17400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
17410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
17420 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
17430 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
17440 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
17450 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17460 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
17470 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
17480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
17490 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
174a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
174b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
174c0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
174d0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
174e0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
174f0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
17500 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
17510 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
17520 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
17530 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
17540 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17550 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
17560 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
17570 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
17580 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
17590 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
175a0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
175b0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
175c0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
175d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
175e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
175f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
17600 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
17610 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
17620 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
17630 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
17640 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
17650 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
17660 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
17670 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
17680 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
17690 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
176a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
176b0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
176c0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
176d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
176e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
176f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17700 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
17710 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
17720 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
17730 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
17740 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
17750 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
17760 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
17770 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
17780 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
17790 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
177a0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
177b0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
177c0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
177d0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
177e0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
177f0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
17800 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
17810 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
17820 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
17830 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
17840 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17850 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
17860 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
17870 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
17880 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
17890 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
178a0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
178b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
178c0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
178d0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
178e0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
178f0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
17900 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
17910 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
17920 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
17930 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
17940 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
17950 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
17960 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
17970 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
17980 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
17990 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
179a0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
179b0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
179c0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
179d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
179e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
179f0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
17a00 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
17a10 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
17a20 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
17a30 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
17a40 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
17a50 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
17a60 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
17a70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17a80 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
17a90 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
17aa0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
17ab0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
17ac0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
17ad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
17ae0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
17af0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
17b00 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
17b10 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
17b20 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
17b30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
17b40 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
17b50 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
17b60 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
17b70 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
17b80 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
17b90 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
17ba0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
17bb0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
17bc0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
17bd0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
17be0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
17bf0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
17c00 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
17c10 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
17c20 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17c30 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
17c40 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
17c50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
17c60 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
17c70 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
17c80 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
17c90 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
17ca0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
17cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
17cc0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
17cd0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
17ce0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
17cf0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
17d00 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
17d10 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
17d20 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
17d30 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
17d40 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
17d50 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
17d60 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
17d70 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
17d80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
17d90 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
17da0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
17db0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
17dc0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
17dd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
17de0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
17df0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
17e00 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
17e10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
17e20 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
17e30 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
17e40 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
17e50 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
17e60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
17e70 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
17e80 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
17e90 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
17ea0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
17eb0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
17ec0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
17ed0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
17ee0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
17ef0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
17f00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
17f10 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
17f20 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
17f30 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
17f40 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
17f50 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
17f60 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
17f70 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
17f80 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
17f90 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
17fa0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
17fb0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
17fc0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
17fd0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
17fe0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
17ff0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
18000 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
18010 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
18020 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
18030 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
18040 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
18050 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
18060 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
18070 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
18080 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
18090 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
180a0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
180b0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
180c0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
180d0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
180e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
180f0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
18100 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
18110 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
18120 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
18130 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
18140 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
18150 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
18160 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
18170 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
18180 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
18190 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
181a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
181b0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
181c0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
181d0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
181e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
181f0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
18200 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
18220 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
18230 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18240 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
18250 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
18260 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
18270 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
18280 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
18290 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
182a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
182b0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
182c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
182d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
182e0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
182f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
18300 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
18310 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
18320 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
18330 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
18340 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
18350 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
18360 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
18370 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
18380 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
18390 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
183a0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
183b0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
183c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
183d0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
183e0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
183f0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
18400 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
18410 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
18420 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
18430 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
18440 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
18450 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
18460 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
18470 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
18480 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
18490 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
184a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
184b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
184c0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
184d0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
184e0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
184f0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
18500 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
18510 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
18520 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
18530 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
18540 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
18550 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
18560 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
18570 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
18580 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
18590 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
185a0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
185b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
185c0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
185d0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
185e0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
185f0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
18600 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
18610 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
18620 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
18630 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
18640 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
18650 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
18660 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
18670 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
18680 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
18690 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
186a0 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
186b0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
186c0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
186d0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
186e0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
186f0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
18700 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
18710 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
18720 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
18730 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
18740 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
18750 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
18760 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
18770 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
18780 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
18790 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
187a0 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
187b0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
187c0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
187d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
187e0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
187f0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
18800 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
18810 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
18820 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
18830 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18840 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
18850 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
18860 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
18870 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
18880 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
18890 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
188a0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
188b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
188c0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
188d0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
188e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
188f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
18900 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
18910 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
18920 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
18930 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
18940 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
18950 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
18960 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
18970 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
18980 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
18990 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
189a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
189b0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
189c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
189d0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
189e0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
189f0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
18a00 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
18a10 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
18a20 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
18a30 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
18a40 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
18a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
18a60 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
18a70 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
18a80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18a90 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
18aa0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
18ab0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
18ac0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
18ad0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
18ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18af0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
18b00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18b10 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
18b20 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
18b30 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
18b40 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
18b50 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
18b60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
18b70 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
18b80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
18b90 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
18ba0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
18bb0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
18bc0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
18bd0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
18be0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
18bf0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
18c00 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
18c10 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
18c20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
18c30 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
18c40 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
18c50 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
18c60 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
18c70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
18c80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18c90 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
18ca0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
18cb0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
18cc0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
18cd0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
18ce0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
18cf0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
18d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
18d10 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
18d20 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
18d30 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
18d40 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
18d50 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
18d60 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
18d70 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
18d80 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
18d90 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
18da0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
18db0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18dc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
18dd0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
18de0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
18df0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
18e00 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
18e10 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
18e20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18e30 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
18e40 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
18e50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18e60 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
18e70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18e80 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
18e90 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
18ea0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
18eb0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
18ec0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
18ed0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
18ee0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
18ef0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
18f00 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
18f10 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
18f20 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
18f30 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
18f40 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
18f50 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
18f60 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
18f70 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
18f80 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
18f90 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
18fa0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
18fb0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
18fc0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
18fd0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
18fe0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
18ff0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
19000 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
19010 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
19020 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
19030 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
19040 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
19050 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
19060 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
19070 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
19080 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
19090 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
190a0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
190b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
190c0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
190d0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
190e0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
190f0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
19100 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
19110 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
19120 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
19130 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
19140 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
19150 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
19160 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
19170 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
19180 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
19190 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
191a0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
191b0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
191c0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
191d0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
191e0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
191f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19200 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
19210 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
19220 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
19230 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
19240 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
19250 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
19260 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
19270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19280 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
19290 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
192a0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
192b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
192c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
192d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
192e0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
192f0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
19300 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
19310 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
19320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19330 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
19340 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
19350 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
19360 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
19370 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
19380 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
19390 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
193a0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
193b0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
193c0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
193d0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
193e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
193f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
19400 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
19410 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
19420 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
19430 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19440 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
19450 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
19460 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
19470 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
19480 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
19490 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
194a0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
194b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
194c0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
194d0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
194e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
194f0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
19500 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
19510 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
19520 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
19530 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
19540 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19550 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
19560 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
19570 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
19580 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
19590 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
195a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
195b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
195c0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
195d0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
195e0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
195f0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
19600 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
19610 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
19620 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19630 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19640 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
19650 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
19660 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
19670 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
19680 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
19690 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
196a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
196b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
196c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
196d0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
196e0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
196f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
19700 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
19710 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
19720 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
19730 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
19740 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19750 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19760 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
19770 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
19780 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
19790 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
197a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
197b0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
197c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
197d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
197e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
197f0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
19800 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
19810 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
19820 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
19830 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
19840 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
19850 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
19860 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
19870 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
19880 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
19890 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
198a0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
198b0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
198c0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
198d0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
198e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
198f0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
19900 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
19910 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
19920 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19930 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
19940 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
19950 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
19960 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
19970 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
19980 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
19990 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
199a0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
199b0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
199c0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
199d0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
199e0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
199f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
19a00 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
19a10 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
19a20 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
19a30 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
19a40 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
19a50 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
19a60 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
19a70 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
19a80 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
19a90 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
19aa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
19ab0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
19ac0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
19ad0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
19ae0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
19af0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
19b00 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
19b10 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
19b20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
19b30 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
19b40 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
19b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
19b60 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
19b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
19b80 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
19b90 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
19ba0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
19bb0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
19bc0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
19bd0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
19be0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
19bf0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
19c00 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
19c10 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
19c20 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
19c30 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
19c40 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
19c50 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
19c60 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
19c70 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
19c80 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
19c90 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
19ca0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
19cb0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
19cc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19cd0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
19ce0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
19cf0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
19d00 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
19d10 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
19d20 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
19d30 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
19d40 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
19d50 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
19d60 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
19d70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
19d80 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
19d90 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
19da0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
19db0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
19dc0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
19dd0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
19de0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
19df0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
19e00 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
19e10 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
19e20 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
19e30 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
19e40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
19e50 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
19e60 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
19e70 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
19e80 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
19e90 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
19ea0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
19eb0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
19ec0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
19ed0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
19ee0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
19ef0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
19f00 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
19f10 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
19f20 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
19f30 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
19f40 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
19f50 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
19f60 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
19f70 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
19f80 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
19f90 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
19fa0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
19fb0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
19fc0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
19fd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
19fe0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
19ff0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1a000 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1a010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1a020 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1a030 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a040 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1a050 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a060 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1a070 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1a080 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1a090 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a0a0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1a0b0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1a0c0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1a0d0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1a0e0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1a0f0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1a100 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1a110 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1a120 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1a130 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1a140 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1a150 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1a160 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1a170 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1a180 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1a190 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1a1a0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1a1b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a1c0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1a1d0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1a1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1a1f0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1a200 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a210 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a220 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1a230 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a240 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1a250 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1a260 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1a270 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1a280 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1a290 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1a2a0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1a2b0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1a2c0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1a2d0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1a2e0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1a2f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1a300 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1a310 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1a320 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1a330 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1a340 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a350 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1a360 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1a370 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1a380 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1a390 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a3a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1a3b0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1a3c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1a3d0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1a3e0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1a3f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1a400 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1a410 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a420 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1a430 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1a440 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1a450 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1a460 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1a470 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1a480 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1a490 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1a4a0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1a4b0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1a4c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a4d0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1a4e0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1a4f0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1a500 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1a510 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1a520 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1a530 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1a540 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
1a550 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
1a560 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
1a570 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1a580 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1a590 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1a5a0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1a5b0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1a5c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1a5d0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1a5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1a5f0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1a600 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1a610 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1a620 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1a630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a640 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1a650 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1a660 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1a670 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1a680 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1a690 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1a6a0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1a6b0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1a6c0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1a6d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1a6e0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1a6f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1a700 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a710 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1a720 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1a730 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1a740 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1a750 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1a760 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1a770 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1a780 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a790 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1a7a0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1a7b0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1a7c0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1a7d0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1a7e0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1a7f0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1a800 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1a810 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1a820 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1a830 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a840 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1a850 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1a860 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1a870 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1a880 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1a890 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a8a0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1a8b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1a8c0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1a8d0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1a8e0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1a8f0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1a900 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1a910 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1a920 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1a930 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1a940 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1a950 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1a960 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1a970 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1a980 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1a990 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1a9a0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1a9b0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1a9c0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1a9d0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1a9e0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1a9f0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1aa00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aa10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aa20 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1aa30 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1aa40 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1aa50 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1aa60 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1aa70 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1aa80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1aa90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1aaa0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1aab0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1aac0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1aad0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1aae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1aaf0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1ab00 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1ab10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ab20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ab30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ab40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1ab50 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1ab60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ab70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ab80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ab90 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1aba0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1abb0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1abc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1abd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1abe0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1abf0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1ac00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1ac10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ac20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ac30 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1ac40 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1ac50 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ac60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ac70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ac80 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1ac90 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1aca0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1acb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1acc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1acd0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1ace0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1acf0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ad00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ad10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ad20 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1ad30 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1ad40 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ad50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ad60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ad70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1ad80 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1ad90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ada0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1adb0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1adc0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1add0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ade0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1adf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ae00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1ae10 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1ae20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ae30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ae40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ae50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1ae60 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1ae70 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ae80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ae90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1aea0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1aeb0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1aec0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1aed0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1aee0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1aef0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1af00 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1af10 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1af20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1af30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1af40 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1af50 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1af60 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1af70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1af80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1af90 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1afa0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1afb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1afc0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1afd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1afe0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1aff0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1b000 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1b010 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1b020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b030 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1b040 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1b050 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1b060 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1b070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b080 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1b090 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1b0a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1b0b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b0c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1b0d0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1b0e0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1b0f0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1b100 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1b120 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1b130 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1b140 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1b150 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1b160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1b170 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1b180 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1b190 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1b1a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b1b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1b1c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1b1d0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1b1e0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1b1f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b200 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1b210 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1b220 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1b230 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1b240 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b250 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1b260 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1b270 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1b280 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b290 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b2a0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1b2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1b2c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b2d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b2e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b2f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b300 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1b310 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b320 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1b330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b340 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1b350 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1b360 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b370 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1b380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b390 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1b3a0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1b3b0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1b3c0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1b3d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b3e0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1b3f0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1b400 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1b410 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1b420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b430 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1b440 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1b450 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1b460 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1b470 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1b480 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1b490 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1b4a0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1b4b0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1b4c0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1b4d0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1b4e0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1b4f0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1b500 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1b510 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1b520 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b530 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1b540 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1b550 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1b560 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1b570 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1b580 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1b590 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1b5a0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1b5b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1b5c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1b5d0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1b5e0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1b5f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b600 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1b610 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1b620 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1b630 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1b640 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1b650 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1b660 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1b670 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1b680 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1b690 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1b6a0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1b6b0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1b6c0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1b6d0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1b6e0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1b6f0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1b700 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1b710 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1b720 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1b730 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1b740 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1b750 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1b760 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1b770 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1b780 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1b790 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1b7a0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1b7b0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1b7c0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1b7d0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1b7e0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1b7f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1b800 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1b810 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1b820 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1b830 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1b840 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1b850 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1b860 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1b870 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1b880 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1b890 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1b8a0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1b8b0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1b8c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1b8d0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1b8e0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1b8f0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1b900 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1b910 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1b920 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1b930 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1b940 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1b950 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1b960 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1b970 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1b980 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1b990 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1b9a0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1b9b0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1b9c0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1b9d0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1b9e0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1b9f0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1ba00 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1ba10 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1ba20 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1ba30 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1ba40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ba50 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1ba60 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1ba70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1ba80 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1ba90 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1baa0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1bab0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1bac0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1bad0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1bae0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1baf0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1bb00 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1bb10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bb20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1bb30 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1bb40 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1bb50 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1bb60 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1bb70 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1bb80 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1bb90 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1bba0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1bbb0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1bbc0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1bbd0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
1bbe0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
1bbf0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
1bc00 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
1bc10 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
1bc20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1bc30 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
1bc40 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
1bc50 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
1bc60 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
1bc70 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
1bc80 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
1bc90 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a  allback X..**.**
1bca0 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
1bcb0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1bcc0 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
1bcd0 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
1bce0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1bcf0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
1bd00 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
1bd10 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
1bd20 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
1bd30 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
1bd40 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
1bd50 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
1bd60 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1bd70 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
1bd80 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
1bd90 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
1bda0 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
1bdb0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
1bdc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
1bdd0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1bde0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1bdf0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1be00 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1be10 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1be20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1be30 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1be40 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1be50 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1be60 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1be70 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1be80 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1be90 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1bea0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1beb0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1bec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bed0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1bee0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1bef0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1bf00 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1bf10 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1bf20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1bf30 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1bf40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bf50 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1bf60 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1bf70 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1bf80 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
1bf90 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1bfa0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1bfb0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1bfc0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1bfd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bfe0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1bff0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1c000 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1c010 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1c020 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1c030 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
1c040 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1c050 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1c060 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1c070 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1c080 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1c090 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1c0a0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1c0b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1c0c0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1c0d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1c0e0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1c0f0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1c100 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c110 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1c120 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1c130 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1c140 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1c150 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1c160 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1c170 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1c180 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c190 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1c1a0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1c1b0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1c1c0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1c1d0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1c1e0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1c1f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1c200 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1c210 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1c220 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c230 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1c240 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1c250 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1c260 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1c270 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1c280 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1c290 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1c2a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1c2b0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1c2c0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1c2d0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1c2e0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1c2f0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1c300 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1c310 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1c320 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1c330 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1c340 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1c350 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1c360 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1c370 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1c380 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1c390 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1c3a0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1c3b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1c3c0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1c3d0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1c3e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1c3f0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1c400 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1c410 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1c420 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1c430 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1c440 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1c450 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1c460 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1c470 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1c480 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1c490 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1c4a0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1c4b0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1c4c0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1c4d0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1c4e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1c4f0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1c500 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1c510 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1c520 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1c530 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1c540 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1c550 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1c560 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1c570 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1c580 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1c590 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1c5a0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1c5b0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1c5c0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1c5d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1c5e0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1c5f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1c600 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1c610 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1c620 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1c630 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1c640 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1c650 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
1c660 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1c670 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
1c680 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1c690 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1c6a0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1c6b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1c6c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c6d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1c6e0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1c6f0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1c700 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1c710 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1c720 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1c730 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1c740 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1c750 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c760 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1c770 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c780 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1c790 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1c7a0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1c7b0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1c7c0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1c7d0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1c7e0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c7f0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1c800 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1c810 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1c820 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1c830 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1c840 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1c850 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1c860 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c870 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1c880 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1c890 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1c8a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c8b0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1c8c0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1c8d0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1c8e0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1c8f0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1c900 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1c910 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1c920 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1c930 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1c940 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1c950 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1c960 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1c970 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c980 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1c990 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1c9a0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1c9b0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
1c9c0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1c9d0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
1c9e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1c9f0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
1ca00 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
1ca10 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1ca20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1ca30 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1ca40 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1ca50 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1ca60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1ca70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1ca80 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1ca90 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1caa0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1cab0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1cac0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1cad0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1cae0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1caf0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1cb00 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1cb10 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1cb20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1cb30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1cb40 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1cb50 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1cb60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1cb70 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1cb80 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1cb90 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1cba0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1cbb0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1cbc0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1cbd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1cbe0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1cbf0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1cc00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1cc10 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1cc20 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1cc30 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1cc40 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1cc50 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1cc60 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1cc70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1cc80 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1cc90 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1cca0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1ccb0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1ccc0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1ccd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cce0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1ccf0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1cd00 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1cd10 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1cd20 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
1cd30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1cd40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1cd50 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1cd60 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1cd70 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1cd80 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1cd90 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1cda0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1cdb0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1cdc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cdd0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1cde0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1cdf0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1ce00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1ce10 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1ce20 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ce30 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1ce40 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1ce50 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1ce60 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1ce70 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1ce80 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1ce90 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1cea0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1ceb0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1cec0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1ced0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1cee0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1cef0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1cf00 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1cf10 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1cf20 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1cf30 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1cf40 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1cf50 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1cf60 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1cf70 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1cf80 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1cf90 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1cfa0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1cfb0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1cfc0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1cfd0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1cfe0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1cff0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1d000 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1d010 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1d020 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1d030 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1d040 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1d050 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1d060 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1d070 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1d080 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1d090 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1d0a0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1d0b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1d0c0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1d0d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d0e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1d0f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
1d100 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
1d110 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
1d120 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
1d130 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
1d140 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
1d150 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1d160 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
1d170 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1d180 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
1d190 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
1d1a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1d1b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1d1c0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
1d1d0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1d1e0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1d1f0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1d200 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
1d210 73 0a 2a 2a 20 69 73 20 73 65 74 20 69 6e 20 74  s.** is set in t
1d220 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1d230 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
1d240 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
1d250 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
1d260 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
1d270 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
1d280 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
1d290 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
1d2a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1d2b0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
1d2c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
1d2d0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
1d2e0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
1d2f0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
1d300 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
1d310 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
1d320 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
1d330 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
1d340 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
1d350 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
1d360 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
1d370 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
1d380 65 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  epretation by de
1d390 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
1d3a0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
1d3b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1d3c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1d3d0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
1d3e0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
1d3f0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
1d400 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
1d410 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
1d420 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
1d430 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1d440 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1d450 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
1d460 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
1d470 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
1d480 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
1d490 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
1d4a0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
1d4b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1d4c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
1d4d0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
1d4e0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1d4f0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
1d500 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
1d510 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
1d520 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
1d530 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
1d540 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1d550 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
1d560 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
1d570 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
1d580 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
1d590 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
1d5a0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
1d5b0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1d5c0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
1d5d0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
1d5e0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
1d5f0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
1d600 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
1d610 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
1d620 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
1d630 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
1d640 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
1d650 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1d660 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
1d670 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
1d680 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
1d690 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
1d6a0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
1d6b0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
1d6c0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
1d6d0 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
1d6e0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
1d6f0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
1d700 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
1d710 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
1d720 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
1d730 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
1d740 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
1d750 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
1d760 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
1d770 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
1d780 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
1d790 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
1d7a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1d7b0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
1d7c0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
1d7d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
1d7e0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
1d7f0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
1d800 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
1d810 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
1d820 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
1d830 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
1d840 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1d850 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1d860 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
1d870 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
1d880 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1d890 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
1d8a0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
1d8b0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
1d8c0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
1d8d0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
1d8e0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
1d8f0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
1d900 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
1d910 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
1d920 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1d930 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
1d940 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
1d950 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
1d960 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
1d970 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
1d980 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
1d990 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
1d9a0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
1d9b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1d9c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1d9d0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1d9e0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
1d9f0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
1da00 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
1da10 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
1da20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
1da30 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  "rw" or.**     "
1da40 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  rwc". Attempting
1da50 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
1da60 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
1da70 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
1da80 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
1da90 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
1daa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1dab0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1dac0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
1dad0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
1dae0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1daf0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
1db00 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
1db10 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
1db20 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1db30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1db40 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
1db50 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
1db60 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
1db70 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1db80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1db90 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
1dba0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
1dbb0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
1dbc0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
1dbd0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
1dbe0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
1dbf0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
1dc00 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
1dc10 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
1dc20 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1dc30 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
1dc40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1dc50 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
1dc60 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66  OPEN_CREATE. ^If
1dc70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1dc80 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73  () is .**     us
1dc90 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72  ed, it is an err
1dca0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
1dcb0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f  value for the mo
1dcc0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
1dcd0 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73  t is .**     les
1dce0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
1dcf0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
1dd00 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 20 70  d by the flags p
1dd10 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
1dd20 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  rd .**     param
1dd30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  eter..**.**   <l
1dd40 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
1dd50 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
1dd60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1dd70 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
1dd80 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
1dd90 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
1dda0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
1ddb0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ddc0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
1ddd0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1dde0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
1ddf0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
1de00 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
1de10 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
1de20 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
1de30 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
1de40 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
1de50 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
1de60 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1de70 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
1de80 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1de90 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
1dea0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1deb0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1dec0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
1ded0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
1dee0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
1def0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
1df00 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
1df10 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
1df20 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
1df30 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
1df40 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1df50 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
1df60 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
1df70 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
1df80 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
1df90 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
1dfa0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
1dfb0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1dfc0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
1dfd0 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
1dfe0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1dff0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
1e000 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
1e010 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
1e020 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
1e030 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
1e040 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
1e050 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
1e060 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
1e070 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1e080 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1e090 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
1e0a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1e0b0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
1e0c0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
1e0d0 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
1e0e0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
1e0f0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
1e100 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
1e110 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
1e120 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
1e130 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1e140 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
1e150 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
1e160 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
1e170 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
1e180 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
1e190 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
1e1a0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
1e1b0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1e1c0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
1e1d0 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
1e1e0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
1e1f0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
1e200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1e210 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1e220 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
1e230 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
1e240 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
1e250 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
1e260 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
1e270 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
1e280 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
1e290 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
1e2a0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
1e2b0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
1e2c0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
1e2d0 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
1e2e0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
1e2f0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
1e300 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
1e310 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
1e320 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
1e330 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
1e340 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
1e350 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
1e360 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
1e370 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
1e380 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
1e390 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
1e3a0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
1e3b0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
1e3c0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
1e3d0 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
1e3e0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
1e3f0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
1e400 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
1e410 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
1e420 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
1e430 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
1e440 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
1e450 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
1e460 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
1e470 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
1e480 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
1e490 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
1e4a0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
1e4b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e4c0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
1e4d0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
1e4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
1e4f0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
1e500 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
1e510 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1e520 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
1e530 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
1e540 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
1e550 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
1e560 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
1e570 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
1e580 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
1e590 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1e5a0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
1e5b0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
1e5c0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
1e5d0 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
1e5e0 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
1e5f0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
1e600 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
1e610 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
1e620 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
1e630 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
1e640 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
1e650 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
1e660 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
1e670 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
1e680 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
1e690 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
1e6a0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
1e6b0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
1e6c0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
1e6d0 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
1e6e0 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
1e6f0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
1e700 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
1e710 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
1e720 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
1e730 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
1e740 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
1e750 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
1e760 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
1e770 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
1e780 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
1e790 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
1e7a0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
1e7b0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
1e7c0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
1e7d0 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
1e7e0 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
1e7f0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
1e800 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
1e810 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
1e820 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
1e830 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
1e840 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1e850 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1e860 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1e870 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1e880 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1e890 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1e8a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1e8b0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1e8c0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1e8d0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1e8e0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1e8f0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1e900 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1e910 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1e920 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1e930 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1e940 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1e950 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1e960 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1e970 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1e980 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  _v2()..*/.int sq
1e990 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1e9a0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1e9b0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1e9c0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1e9d0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1e9e0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1e9f0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1ea00 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1ea10 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1ea20 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1ea30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1ea40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1ea50 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1ea60 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1ea70 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1ea80 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ea90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1eaa0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1eab0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1eac0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1ead0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1eae0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1eaf0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1eb00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1eb10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1eb20 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1eb30 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1eb40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1eb50 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1eb60 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1eb70 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1eb80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1eb90 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
1eba0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
1ebb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1ebc0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
1ebd0 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
1ebe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
1ebf0 20 74 68 61 74 20 63 68 65 63 6b 73 0a 2a 2a 20   that checks.** 
1ec00 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
1ec10 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
1ec20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
1ec30 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
1ec40 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
1ec50 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
1ec60 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
1ec70 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
1ec80 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
1ec90 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d   zFilename argum
1eca0 65 6e 74 20 69 73 20 74 68 65 20 66 69 6c 65 6e  ent is the filen
1ecb0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
1ecc0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
1ecd0 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  n().** method of
1ece0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
1ecf0 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a 50 61 72  ation.  The zPar
1ed00 61 6d 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  am argument is t
1ed10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1ed20 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
1ed30 72 20 77 65 20 73 65 65 6b 2e 20 20 54 68 69 73  r we seek.  This
1ed40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1ed50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1ed60 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70 61 72 61  e zParam.** para
1ed70 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
1ed80 74 73 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  ts.  If the para
1ed90 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f 74 20 65  meter does not e
1eda0 78 69 73 74 2c 20 74 68 69 73 20 72 6f 75 74 69  xist, this routi
1edb0 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ne.** returns a 
1edc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1edd0 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
1ede0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1edf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
1ee00 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
1ee10 74 68 61 74 20 53 51 4c 69 74 65 0a 2a 2a 20 70  that SQLite.** p
1ee20 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
1ee30 4f 70 65 6e 20 56 46 53 20 6d 65 74 68 6f 64 2c  Open VFS method,
1ee40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1ee50 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
1ee60 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ne.** is undefin
1ee70 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
1ee80 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
1ee90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1eea0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
1eeb0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
1eec0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
1eed0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a  har *zParam);...
1eee0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1eef0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1ef00 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1ef10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1ef20 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1ef30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ef40 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1ef50 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1ef60 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1ef70 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1ef80 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1ef90 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1efa0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1efb0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1efc0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1efd0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1efe0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1eff0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1f000 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1f010 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1f020 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1f030 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1f040 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1f050 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f060 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1f070 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1f080 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1f090 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1f0a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1f0b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1f0c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1f0d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1f0e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1f0f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f100 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1f110 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f120 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1f130 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1f140 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1f150 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1f160 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1f170 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1f180 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1f190 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1f1a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1f1b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1f1c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1f1d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1f1e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1f1f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1f200 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1f210 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1f220 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1f230 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1f240 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1f250 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1f260 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1f270 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1f280 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1f290 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1f2a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1f2b0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1f2c0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1f2d0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1f2e0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1f2f0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1f300 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1f310 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1f320 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1f330 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1f340 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1f350 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1f360 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1f370 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1f380 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1f390 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1f3a0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1f3b0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1f3c0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1f3d0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1f3e0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1f3f0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1f400 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1f410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f420 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1f430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1f440 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1f450 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1f460 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1f470 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1f480 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1f490 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1f4a0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1f4b0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1f4c0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1f4d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1f4e0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1f4f0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1f500 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1f510 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1f520 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1f530 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1f540 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1f550 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1f560 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1f570 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1f580 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1f590 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1f5a0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1f5b0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
1f5c0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1f5d0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1f5e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f5f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1f600 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1f610 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1f620 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1f630 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1f640 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1f650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f660 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1f670 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1f680 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1f690 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1f6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1f6b0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1f6c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1f6d0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1f6e0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1f6f0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1f700 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1f710 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1f720 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1f730 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1f740 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1f750 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1f760 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1f770 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1f780 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1f790 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1f7a0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1f7b0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1f7c0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1f7d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f7e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f7f0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1f800 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1f810 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1f820 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1f830 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1f840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1f850 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1f860 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1f870 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1f880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1f890 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1f8a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1f8b0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1f8c0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1f8d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1f8e0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1f8f0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1f900 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1f910 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1f920 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1f930 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1f940 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1f950 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1f960 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1f970 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1f980 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1f990 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1f9a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1f9b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1f9c0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1f9d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1f9e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f9f0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
1fa00 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
1fa10 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1fa20 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1fa30 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1fa40 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1fa50 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1fa60 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1fa70 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1fa80 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1fa90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1faa0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1fab0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1fac0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1fad0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1fae0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1faf0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1fb00 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1fb10 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1fb20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1fb30 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1fb40 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1fb50 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1fb60 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1fb70 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
1fb80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1fb90 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1fba0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1fbb0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1fbc0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
1fbd0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
1fbe0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
1fbf0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
1fc00 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1fc10 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1fc20 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
1fc30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
1fc40 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1fc50 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
1fc60 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1fc70 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
1fc80 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1fc90 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1fca0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1fcb0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1fcc0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1fcd0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1fce0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1fcf0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1fd00 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1fd10 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1fd20 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1fd30 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
1fd40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1fd50 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
1fd60 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
1fd70 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
1fd80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fd90 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
1fda0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
1fdb0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
1fdc0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
1fdd0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
1fde0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
1fdf0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
1fe00 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
1fe10 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
1fe20 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
1fe30 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
1fe40 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1fe50 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1fe60 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1fe70 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1fe80 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1fe90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1fea0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1feb0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1fec0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1fed0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1fee0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1fef0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1ff00 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1ff10 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1ff20 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1ff30 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1ff40 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1ff50 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1ff60 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1ff70 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1ff80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1ff90 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1ffa0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1ffb0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1ffc0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1ffd0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1ffe0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1fff0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
20000 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
20010 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
20020 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
20030 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
20040 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
20050 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
20060 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
20070 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
20080 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
20090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
200a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
200b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
200c0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
200d0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
200e0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
200f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
20100 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
20110 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
20120 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
20130 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
20140 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
20150 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
20160 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
20170 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
20180 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
20190 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
201a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
201b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
201c0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
201d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
201e0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
201f0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
20200 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
20210 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
20220 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
20230 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
20240 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
20250 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
20260 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
20270 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
20280 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
20290 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
202a0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
202b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
202c0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
202d0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
202e0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
202f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
20300 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
20310 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
20320 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
20330 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
20340 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
20350 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20360 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
20370 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20380 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
20390 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
203a0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
203b0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
203c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
203d0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
203e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
203f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
20400 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20410 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
20420 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
20430 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
20440 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
20450 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
20460 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
20470 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
20480 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20490 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
204a0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
204b0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
204c0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
204d0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
204e0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
204f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
20500 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
20510 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
20520 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
20530 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
20540 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
20550 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
20560 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20570 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
20580 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20590 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
205a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
205b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
205c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
205d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
205e0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
205f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20600 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
20610 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20620 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20630 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
20640 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
20650 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
20660 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
20670 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
20680 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20690 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
206a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
206b0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
206c0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
206d0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
206e0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
206f0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
20700 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
20710 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
20720 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
20730 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
20740 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
20750 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
20760 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
20770 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
20780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20790 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
207a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
207b0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
207c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
207d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
207e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
207f0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
20800 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20810 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
20820 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
20830 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
20840 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20850 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
20860 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
20870 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
20880 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
20890 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
208a0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
208b0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
208c0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
208d0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
208e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
208f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
20900 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
20910 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
20920 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
20930 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
20940 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
20950 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
20960 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
20970 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
20980 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
20990 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
209a0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
209b0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
209c0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
209d0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
209e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
209f0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
20a00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20a10 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
20a20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20a30 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
20a40 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
20a50 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
20a60 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
20a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20a80 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
20a90 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
20aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20ab0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
20ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
20ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20ae0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
20af0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20b10 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
20b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20b30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
20b40 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
20b50 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
20b60 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
20b70 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
20b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20b90 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
20ba0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
20bb0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
20bc0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
20bd0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
20be0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
20bf0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
20c00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
20c10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
20c20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
20c30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
20c40 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
20c50 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
20c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
20c70 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
20c80 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
20c90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
20ca0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
20cb0 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
20cc0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
20cd0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
20ce0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
20cf0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
20d00 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
20d10 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
20d20 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
20d30 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
20d40 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
20d50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
20d60 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
20d70 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
20d80 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
20d90 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
20da0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
20db0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
20dc0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
20dd0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
20de0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
20df0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
20e00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
20e10 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
20e20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
20e30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
20e40 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
20e50 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
20e60 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
20e70 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
20e80 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
20e90 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
20ea0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
20eb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20ec0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
20ed0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
20ee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20ef0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
20f00 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
20f10 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
20f20 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
20f30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
20f40 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
20f50 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
20f60 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
20f70 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
20f80 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
20f90 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
20fa0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
20fb0 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
20fc0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
20fd0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
20fe0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
20ff0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
21000 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
21010 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
21020 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
21030 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
21040 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
21050 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
21060 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
21070 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
21080 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
21090 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
210a0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
210b0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
210c0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
210d0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
210e0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
210f0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
21100 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
21110 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
21120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
21130 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
21140 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
21150 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
21160 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
21170 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  bytes..**.** ^If
21180 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
21190 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
211a0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
211b0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
211c0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
211d0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
211e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
211f0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
21200 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
21210 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
21220 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
21230 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
21240 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
21250 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
21260 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
21270 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
21280 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
21290 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
212a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
212b0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
212c0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
212d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
212e0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
212f0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
21300 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
21310 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
21320 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
21330 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
21340 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
21350 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
21360 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
21370 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
21380 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
21390 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
213a0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
213b0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
213c0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
213d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
213e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
213f0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
21400 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
21410 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
21420 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
21430 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
21440 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
21450 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
21460 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
21470 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
21480 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
21490 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
214a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
214b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
214c0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
214d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
214e0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
214f0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
21500 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
21510 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
21520 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
21530 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
21540 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
21550 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
21560 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
21570 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
21580 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
21590 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
215a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
215b0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
215c0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
215d0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
215e0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
215f0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
21600 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
21610 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
21620 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
21630 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
21640 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
21650 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
21660 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
21670 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
21680 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
21690 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
216a0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
216b0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
216c0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
216d0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
216e0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
216f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
21700 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
21710 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
21720 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
21730 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
21740 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
21750 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
21760 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21770 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
21780 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
21790 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
217a0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
217b0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
217c0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
217d0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
217e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
217f0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
21800 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
21810 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
21820 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
21830 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21840 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
21850 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
21860 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
21870 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
21880 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
21890 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
218a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
218b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
218c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
218d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
218e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
218f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
21900 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
21910 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
21920 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
21930 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
21940 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
21950 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
21960 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
21970 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
21980 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
21990 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
219a0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
219b0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
219c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
219d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
219e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
219f0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
21a00 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
21a10 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
21a20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
21a30 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
21a40 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
21a50 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
21a60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
21a70 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
21a80 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
21a90 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
21aa0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
21ab0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
21ac0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
21ad0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
21ae0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
21af0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
21b00 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
21b10 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
21b20 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
21b30 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
21b40 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
21b50 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
21b60 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
21b70 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
21b80 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20  E_ENABLE_STAT2] 
21b90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21ba0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
21bb0 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
21bc0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
21bd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21be0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
21bf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
21c00 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
21c10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
21c20 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
21c30 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
21c40 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
21c50 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
21c60 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
21c70 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
21c80 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
21c90 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
21ca0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
21cb0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
21cc0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
21cd0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
21ce0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
21cf0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
21d00 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
21d10 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
21d20 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
21d30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
21d40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
21d50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
21d60 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
21d70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
21d80 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
21d90 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
21da0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
21db0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
21dc0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
21dd0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
21de0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
21df0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
21e00 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
21e10 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
21e20 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
21e30 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
21e40 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
21e50 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
21e60 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
21e70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
21e80 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
21e90 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
21ea0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
21eb0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
21ec0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
21ed0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
21ee0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
21ef0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
21f00 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
21f10 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
21f20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
21f30 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
21f40 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
21f50 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
21f60 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
21f70 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
21f80 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
21f90 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
21fa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21fb0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
21fc0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
21fd0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
21fe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
21ff0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
22000 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
22010 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
22020 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
22030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22040 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
22050 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
22060 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
22070 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
22080 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
22090 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
220a0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
220b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
220c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
220d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
220e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
220f0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
22100 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
22110 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
22120 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
22130 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
22140 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
22150 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
22160 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
22170 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
22180 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
22190 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
221a0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
221b0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
221c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
221d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
221e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
221f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22200 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
22210 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22230 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
22240 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
22250 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
22260 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
22270 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
22280 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
22290 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
222a0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
222b0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
222c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
222d0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
222e0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
222f0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
22300 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
22310 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
22320 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
22330 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
22340 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
22350 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
22360 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
22370 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
22380 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
22390 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
223a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
223b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
223c0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
223d0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
223e0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
223f0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
22400 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
22410 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
22420 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
22430 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
22440 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
22450 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
22460 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
22470 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
22480 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
22490 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
224a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
224b0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
224c0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
224d0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
224e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
224f0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
22500 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
22510 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
22520 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
22530 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
22540 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
22550 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
22560 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
22570 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
22580 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
22590 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
225a0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
225b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
225c0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
225d0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
225e0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
225f0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
22600 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
22610 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
22620 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
22630 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
22640 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
22650 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
22660 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
22670 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
22680 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
22690 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
226a0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
226b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
226c0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
226d0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
226e0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
226f0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
22700 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
22710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22720 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
22730 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
22740 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
22750 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
22760 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
22770 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
22780 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
22790 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
227a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
227b0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
227c0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
227d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
227e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
227f0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
22800 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22810 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
22820 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
22830 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
22840 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
22850 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
22860 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
22870 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
22880 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
22890 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
228a0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
228b0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
228c0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
228d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
228e0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
228f0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
22900 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
22910 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
22920 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
22930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22940 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
22950 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
22960 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
22970 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
22980 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
22990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
229a0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
229b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
229c0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
229d0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
229e0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
229f0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
22a00 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
22a10 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
22a20 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
22a30 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
22a40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22a50 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
22a60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22a70 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
22a80 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
22a90 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
22aa0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
22ab0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
22ac0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
22ad0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
22ae0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
22af0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
22b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22b10 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
22b20 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
22b30 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
22b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22b50 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
22b60 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
22b70 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
22b80 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
22b90 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
22ba0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
22bb0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
22bc0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
22bd0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
22be0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
22bf0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
22c00 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
22c10 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
22c20 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
22c30 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
22c40 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
22c50 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
22c60 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
22c70 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
22c80 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
22c90 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
22ca0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
22cb0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
22cc0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
22cd0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
22ce0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
22cf0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
22d00 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
22d10 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
22d20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
22d30 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
22d40 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
22d50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
22d60 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
22d70 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
22d80 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
22d90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
22da0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
22db0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
22dc0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
22dd0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
22de0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
22df0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
22e00 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
22e10 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
22e20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
22e30 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
22e40 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
22e50 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
22e60 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
22e70 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
22e80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22e90 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
22ea0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
22eb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
22ec0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
22ed0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
22ee0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
22ef0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
22f00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
22f10 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
22f20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
22f30 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
22f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22f50 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
22f60 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
22f70 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
22f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
22f90 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
22fa0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
22fb0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
22fc0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
22fd0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
22fe0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
22ff0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
23000 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
23010 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
23020 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
23030 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
23040 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
23050 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
23060 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
23070 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
23080 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
23090 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
230a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
230b0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
230c0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
230d0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
230e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
230f0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
23100 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
23110 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
23120 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
23130 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
23140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
23150 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
23160 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
23170 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
23180 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
23190 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
231a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
231b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
231c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
231d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
231e0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
231f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
23200 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
23210 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
23220 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
23230 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
23240 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
23250 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
23260 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
23270 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
23280 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
23290 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
232a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
232b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
232c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
232d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
232e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
232f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
23300 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
23310 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
23320 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
23330 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
23340 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
23350 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
23360 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
23370 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
23380 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
23390 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
233a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
233b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
233c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
233d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
233e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
233f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
23400 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
23410 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
23420 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
23430 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
23440 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
23450 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
23460 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
23470 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
23480 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
23490 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
234a0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
234b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
234c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
234d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
234e0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
234f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
23500 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
23510 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
23520 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
23530 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
23540 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
23550 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
23560 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
23570 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
23580 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
23590 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
235a0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
235b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
235c0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
235d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
235e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
235f0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
23600 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
23610 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
23620 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
23630 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
23640 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
23650 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
23660 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
23670 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
23680 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
23690 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
236a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
236b0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
236c0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
236d0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
236e0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
236f0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
23700 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
23710 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
23720 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
23730 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
23740 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
23750 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
23760 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
23770 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
23780 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
23790 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
237a0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
237b0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
237c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
237d0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
237e0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
237f0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
23800 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
23810 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23820 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
23830 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
23840 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
23850 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
23860 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
23870 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
23880 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
23890 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
238a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
238b0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
238c0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
238d0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
238e0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
238f0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
23900 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
23910 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nator..**.** ^Th
23920 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
23930 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
23940 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
23950 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
23960 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
23970 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
23980 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
23990 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
239a0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
239b0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
239c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
239d0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
239e0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
239f0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
23a00 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
23a10 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
23a20 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
23a30 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
23a40 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
23a50 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
23a60 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
23a70 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
23a80 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
23a90 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
23aa0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
23ab0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
23ac0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
23ad0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
23ae0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
23af0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
23b00 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
23b10 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
23b20 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
23b30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
23b40 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
23b50 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
23b60 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
23b70 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
23b80 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
23b90 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
23ba0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
23bb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23bc0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
23bd0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
23be0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
23bf0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
23c00 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
23c10 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
23c20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
23c30 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
23c40 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
23c50 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
23c60 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
23c70 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
23c80 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
23c90 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
23ca0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
23cb0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
23cc0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
23cd0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
23ce0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
23cf0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
23d00 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
23d10 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
23d20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
23d30 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
23d40 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
23d50 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
23d60 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
23d70 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
23d80 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
23d90 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
23da0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
23db0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
23dc0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
23dd0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
23de0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23df0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
23e00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23e10 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
23e20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23e30 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
23e40 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
23e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
23e60 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
23e70 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
23e80 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
23e90 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
23ea0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
23eb0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
23ec0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
23ed0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
23ee0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
23ef0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
23f00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
23f10 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
23f20 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
23f30 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
23f40 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
23f50 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
23f60 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
23f70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
23f80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
23f90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
23fa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
23fb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
23fc0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
23fd0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
23fe0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
23ff0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
24000 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
24010 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
24020 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
24030 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
24040 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
24050 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
24060 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
24070 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
24080 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24090 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
240a0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
240b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
240c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
240d0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
240e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
240f0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
24100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24110 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
24120 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
24130 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
24140 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
24150 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
24160 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
24170 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
24180 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24190 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
241a0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
241b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
241c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
241d0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
241e0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
241f0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
24200 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24210 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
24220 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
24230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24240 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
24250 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
24260 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
24270 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
24280 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
24290 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
242a0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
242b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
242c0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
242d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
242e0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
242f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24300 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
24310 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24320 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
24330 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
24340 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
24350 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
24360 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
24370 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
24380 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
24390 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
243a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
243b0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
243c0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
243d0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
243e0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
243f0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
24400 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
24410 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
24420 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
24430 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
24440 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
24450 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
24460 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
24470 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
24480 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
24490 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
244a0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
244b0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
244c0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
244d0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
244e0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
244f0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
24500 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
24510 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
24520 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
24530 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
24540 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
24550 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
24560 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
24570 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
24580 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24590 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
245a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
245b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
245c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
245d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
245e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
245f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
24600 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24610 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
24620 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
24630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24640 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
24650 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
24660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
24670 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
24680 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
24690 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
246a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
246b0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
246c0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
246d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
246e0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
246f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
24700 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
24710 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
24720 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
24730 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
24740 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
24750 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
24760 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
24770 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
24780 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
24790 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
247a0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
247b0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
247c0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
247d0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
247e0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
247f0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
24800 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
24810 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
24820 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
24830 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
24840 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
24850 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
24860 72 73 22 2e 0a 2a 2a 20 5e 41 6e 79 20 70 61 72  rs"..** ^Any par
24870 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6f  ameter that is o
24880 70 74 69 6d 69 7a 65 64 20 6f 75 74 20 6f 66 20  ptimized out of 
24890 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
248a0 74 65 6d 65 6e 74 20 62 79 20 74 68 65 20 0a 2a  tement by the .*
248b0 2a 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  * query planner 
248c0 62 65 63 6f 6d 65 73 20 61 20 6e 61 6d 65 6c 65  becomes a namele
248d0 73 73 20 6f 72 20 61 6e 6f 6e 79 6d 6f 75 73 20  ss or anonymous 
248e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
248f0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
24900 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
24910 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
24920 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
24930 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
24940 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
24950 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
24960 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
24970 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
24980 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
24990 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
249a0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
249b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
249c0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
249d0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
249e0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
249f0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
24a00 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
24a10 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
24a20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24a30 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
24a40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24a50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
24a60 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
24a70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
24a80 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
24a90 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
24aa0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24ab0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
24ac0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24ad0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24ae0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
24af0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
24b00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
24b10 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
24b20 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
24b30 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
24b40 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
24b50 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
24b60 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
24b70 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
24b80 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
24b90 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
24ba0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
24bb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
24bc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24bd0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
24be0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
24bf0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
24c00 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
24c10 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
24c20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
24c30 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
24c40 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
24c50 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
24c60 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
24c70 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
24c80 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
24c90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24ca0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
24cb0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
24cc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24cd0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
24ce0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
24cf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
24d00 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
24d10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24d20 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
24d30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24d40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
24d50 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
24d60 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
24d70 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
24d80 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
24d90 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
24da0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
24db0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
24dc0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
24dd0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
24de0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24df0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
24e00 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
24e10 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
24e20 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
24e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
24e40 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
24e50 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
24e60 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
24e70 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
24e80 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
24e90 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
24ea0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
24eb0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
24ec0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
24ed0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
24ee0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
24ef0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
24f00 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
24f10 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
24f20 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
24f30 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
24f40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
24f50 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
24f60 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
24f70 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
24f80 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
24f90 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
24fa0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
24fb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24fc0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
24fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
24fe0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
24ff0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
25000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25010 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
25020 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
25030 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
25040 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
25050 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
25060 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
25070 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
25080 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
25090 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
250a0 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
250b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
250c0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
250d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
250e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
250f0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
25100 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
25110 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
25120 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
25130 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
25140 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
25150 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
25160 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25170 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25180 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
25190 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
251a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
251b0 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
251c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
251d0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
251e0 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
251f0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
25200 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
25210 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
25220 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
25230 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
25240 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25250 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
25260 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
25270 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25280 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
25290 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
252a0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
252b0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
252c0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
252d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
252e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
252f0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
25300 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
25310 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
25320 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
25330 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
25340 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
25350 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
25360 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
25370 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
25380 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
25390 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
253a0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
253b0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
253c0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
253d0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
253e0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
253f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25400 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
25410 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
25420 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
25430 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
25440 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
25450 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
25460 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
25470 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
25480 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
25490 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
254a0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
254b0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
254c0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
254d0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
254e0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
254f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
25500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
25510 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25520 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
25530 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25540 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
25550 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
25560 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
25570 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
25580 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
25590 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
255a0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
255b0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
255c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
255d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
255e0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
255f0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
25600 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
25610 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
25620 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
25630 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
25640 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
25650 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
25660 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
25670 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
25680 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
25690 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
256a0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
256b0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
256c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
256d0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
256e0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
256f0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
25700 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
25710 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
25720 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
25730 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
25740 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
25750 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
25760 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
25770 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
25780 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
25790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
257a0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
257b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
257c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
257d0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
257e0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
257f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25800 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
25810 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
25820 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
25830 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
25840 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
25850 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
25860 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
25870 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
25880 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
25890 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
258a0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
258b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
258c0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
258d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
258e0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
258f0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
25900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25910 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
25920 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
25930 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
25940 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
25950 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
25960 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
25970 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
25980 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
25990 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
259a0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
259b0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
259c0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
259d0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
259e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
259f0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
25a00 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
25a10 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
25a20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
25a30 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
25a40 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
25a50 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
25a60 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
25a70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
25a80 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
25a90 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
25aa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
25ab0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
25ac0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
25ad0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
25ae0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
25af0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
25b00 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
25b10 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
25b20 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
25b30 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
25b40 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
25b50 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
25b60 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
25b70 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
25b80 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
25b90 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
25ba0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
25bb0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
25bc0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
25bd0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
25be0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
25bf0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
25c00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
25c10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
25c20 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
25c30 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
25c40 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
25c50 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
25c60 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
25c70 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
25c80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
25c90 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
25ca0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25cb0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
25cc0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
25cd0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
25ce0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
25cf0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
25d00 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
25d10 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
25d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
25d30 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25d40 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
25d50 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
25d60 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
25d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25d80 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
25d90 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
25da0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
25db0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
25dc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
25dd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25de0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25df0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
25e00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25e10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25e20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
25e30 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25e40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25e50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25e60 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
25e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25e80 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
25e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25ea0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
25eb0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25ee0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
25ef0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25f00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25f10 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
25f20 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25f30 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
25f40 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
25f50 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
25f60 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
25f70 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
25f80 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
25f90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25fa0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
25fb0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
25fc0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25fd0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
25fe0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
25ff0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
26000 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
26010 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
26020 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
26030 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
26040 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
26050 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
26060 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
26070 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
26080 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
26090 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
260a0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
260b0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
260c0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
260d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
260e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
260f0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
26100 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
26110 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
26120 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
26130 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
26140 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
26150 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
26160 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
26170 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
26180 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
26190 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
261a0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
261b0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
261c0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
261d0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
261e0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
261f0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
26200 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
26210 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
26220 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
26230 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
26240 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
26250 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
26260 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
26270 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
26280 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
26290 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
262a0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
262b0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
262c0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
262d0 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
262e0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
262f0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
26300 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
26310 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
26320 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
26330 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
26340 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
26350 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
26360 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
26370 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
26380 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
26390 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
263a0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
263b0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
263c0 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
263d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
263e0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
263f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
26400 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
26420 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
26430 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
26440 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
26450 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
26460 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
26470 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26480 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
26490 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
264a0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
264b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
264c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
264d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
264e0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
264f0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
26500 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26510 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26520 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
26530 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
26540 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
26550 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
26560 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
26570 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
26580 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
26590 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
265a0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
265b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
265c0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
265d0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
265e0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
265f0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
26600 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
26610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26620 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
26630 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26640 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
26650 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26660 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
26670 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
26680 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26690 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
266a0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
266b0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
266c0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
266d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
266e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
266f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
26700 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
26710 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
26720 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
26730 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
26740 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
26750 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
26760 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
26770 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
26780 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
26790 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
267a0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
267b0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
267c0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
267d0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
267e0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
267f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
26800 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
26810 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
26820 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
26830 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
26840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
26850 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
26860 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
26870 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
26880 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
26890 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
268a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
268b0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
268c0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
268d0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
268e0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
268f0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
26900 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
26910 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
26920 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
26930 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
26940 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
26950 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
26960 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
26970 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
26980 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
26990 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
269a0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
269b0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
269c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
269d0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
269e0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
269f0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
26a00 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
26a10 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
26a20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
26a30 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
26a40 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
26a50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26a60 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
26a70 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
26a80 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
26a90 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
26aa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
26ab0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
26ac0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
26ad0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
26ae0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
26af0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
26b00 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
26b10 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
26b20 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
26b30 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
26b40 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
26b50 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
26b60 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
26b70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
26b80 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
26b90 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
26ba0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
26bb0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
26bc0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
26bd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
26be0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
26bf0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
26c00 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
26c10 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
26c20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
26c30 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
26c40 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
26c50 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
26c60 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
26c70 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
26c80 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
26c90 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
26ca0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
26cb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
26cc0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
26cd0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
26ce0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
26cf0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
26d00 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
26d10 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
26d20 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
26d30 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
26d40 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
26d50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26d60 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
26d70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
26d80 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
26d90 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
26da0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
26db0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
26dc0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
26dd0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
26de0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
26df0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
26e00 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
26e10 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
26e20 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
26e30 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
26e40 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
26e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26e60 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
26e70 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
26e80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
26e90 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
26ea0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
26eb0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
26ec0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
26ed0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
26ee0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
26ef0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
26f00 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
26f10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26f20 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
26f30 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
26f40 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
26f50 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
26f60 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
26f70 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
26f80 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
26f90 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
26fa0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
26fb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
26fc0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
26fd0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
26fe0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
26ff0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
27000 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
27010 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
27020 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
27030 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
27040 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
27050 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
27060 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27070 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
27080 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27090 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
270a0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
270b0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
270c0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
270d0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
270e0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
270f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
27100 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
27110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27120 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
27130 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
27140 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
27150 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
27160 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
27170 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
27180 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
27190 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
271a0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
271b0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
271c0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
271d0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
271e0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
271f0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
27200 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
27210 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
27220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
27230 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
27240 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
27250 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
27260 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
27270 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
27280 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
27290 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
272a0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
272b0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
272c0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
272d0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
272e0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
272f0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
27300 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
27310 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
27320 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
27330 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
27340 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27350 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
27360 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
27370 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
27380 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
27390 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
273a0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
273b0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
273c0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
273d0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
273e0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
273f0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
27400 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
27410 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
27420 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
27430 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
27440 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
27450 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
27460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27470 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27480 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
27490 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
274a0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
274b0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
274c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
274d0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
274e0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
274f0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
27500 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
27510 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
27520 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
27530 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
27540 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
27550 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
27560 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
27570 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
27580 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27590 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
275a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
275b0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
275c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
275d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
275e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
275f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
27600 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
27610 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
27620 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
27630 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27640 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
27650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27660 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
27670 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
27680 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
27690 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
276a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
276b0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
276c0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
276d0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
276e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
276f0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
27700 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
27710 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
27720 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
27730 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
27740 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
27750 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
27770 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
27780 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
27790 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
277a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
277b0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
277c0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
277d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
277e0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
277f0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
27800 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
27810 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
27820 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
27830 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
27840 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
27850 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
27860 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
27870 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
27880 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
27890 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
278a0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
278b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
278c0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
278d0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
278e0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
278f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
27900 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
27910 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
27920 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
27930 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
27940 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
27950 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
27960 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
27970 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
27980 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
27990 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
279a0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
279b0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
279c0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
279d0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
279e0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
279f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
27a00 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
27a10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
27a20 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
27a30 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
27a40 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
27a50 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
27a60 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
27a70 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
27a80 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
27a90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
27aa0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
27ab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
27ac0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
27ad0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
27ae0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
27af0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
27b00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27b10 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
27b20 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
27b30 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
27b40 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
27b50 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
27b60 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
27b70 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
27b80 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
27b90 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
27ba0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
27bb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
27bc0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
27bd0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
27be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
27bf0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
27c00 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
27c10 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
27c20 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
27c30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
27c40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
27c50 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
27c60 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
27c70 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
27c80 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
27c90 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
27ca0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
27cb0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
27cc0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
27cd0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
27ce0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
27cf0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
27d00 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
27d10 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
27d20 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
27d30 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
27d40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27d50 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
27d60 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
27d70 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
27d80 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
27d90 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
27da0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
27db0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
27dc0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
27dd0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
27de0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
27df0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
27e00 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
27e10 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
27e20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
27e30 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
27e40 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
27e50 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
27e60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27e70 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
27e80 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
27e90 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
27ea0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
27eb0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
27ec0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
27ed0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
27ee0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
27ef0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27f00 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
27f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
27f20 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
27f30 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27f40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
27f50 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
27f60 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
27f70 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
27f80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27f90 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
27fa0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27fb0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
27fc0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
27fd0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
27fe0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27ff0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
28000 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
28010 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
28020 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
28030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28040 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
28050 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
28060 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
28070 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
28080 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
28090 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
280a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
280b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
280c0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
280d0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
280e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
280f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
28100 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
28110 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
28120 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
28130 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
28140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28150 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
28160 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
28170 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
28180 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
28190 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
281a0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
281b0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
281c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
281d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
281e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
281f0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
28200 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
28210 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
28220 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
28230 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
28240 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
28250 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
28260 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
28270 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28280 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
28290 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
282a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
282b0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
282c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
282d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
282e0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
282f0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
28300 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
28310 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
28320 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28330 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
28340 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
28350 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
28360 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
28370 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
28380 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
28390 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
283a0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
283b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
283c0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
283d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
283e0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
283f0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
28400 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
28410 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
28420 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
28430 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
28440 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
28450 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
28460 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
28470 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
28480 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28490 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
284a0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
284b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
284c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
284d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
284e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
284f0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
28500 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
28510 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
28520 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
28530 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
28540 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
28550 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
28560 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
28570 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
28580 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
28590 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
285a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
285b0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
285c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
285d0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
285e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
285f0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
28600 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
28610 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
28620 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
28630 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28640 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
28650 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
28660 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
28670 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28680 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
28690 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
286a0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
286b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
286c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
286d0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
286e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
286f0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
28700 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
28710 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
28720 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
28730 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
28740 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
28750 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
28760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28770 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
28780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28790 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
287a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
287b0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
287c0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
287d0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
287e0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
287f0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
28810 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28820 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
28830 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
28840 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
28850 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
28860 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
28870 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
28880 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
28890 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
288a0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
288b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
288c0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
288d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
288e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
288f0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
28900 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28910 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
28920 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
28930 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28940 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
28950 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
28960 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
28970 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
28980 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
28990 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
289a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
289b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
289c0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
289d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
289e0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
289f0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
28a00 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
28a10 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
28a20 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
28a30 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
28a40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
28a50 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
28a60 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
28a70 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28a80 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
28a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
28aa0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
28ab0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
28ac0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
28ad0 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
28ae0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
28af0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
28b00 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
28b10 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
28b20 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
28b30 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
28b40 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
28b50 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
28b60 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
28b70 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
28b80 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
28b90 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
28ba0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
28bb0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
28bc0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
28bd0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
28be0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
28bf0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
28c00 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
28c10 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
28c20 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
28c30 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
28c40 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28c50 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28c60 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28c70 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
28c80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
28c90 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
28ca0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
28cb0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
28cc0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
28cd0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
28ce0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
28cf0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
28d00 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28d10 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
28d20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
28d30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
28d40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
28d50 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
28d60 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
28d70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
28d80 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
28d90 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
28da0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
28db0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
28dc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
28dd0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
28de0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
28df0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
28e00 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
28e10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
28e20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
28e30 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
28e40 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
28e50 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
28e60 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
28e70 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
28e80 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
28e90 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
28ea0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
28eb0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
28ec0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
28ed0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
28ee0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
28ef0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
28f00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
28f10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
28f20 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
28f30 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
28f40 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28f50 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
28f60 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
28f70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
28f80 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
28f90 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
28fa0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
28fb0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
28fc0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
28fd0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
28fe0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
28ff0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
29000 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
29010 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
29020 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
29030 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
29040 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
29050 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
29060 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
29070 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
29080 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
29090 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
290a0 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
290b0 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
290c0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
290d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
290e0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
290f0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
29100 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
29110 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
29120 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
29130 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
29140 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
29150 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
29160 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
29170 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
29180 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
29190 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
291a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
291b0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
291c0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
291d0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
291e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
291f0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
29200 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
29210 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29220 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
29230 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
29240 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
29250 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
29260 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
29270 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
29280 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
29290 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
292a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
292b0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
292c0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
292d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
292e0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
292f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29300 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
29310 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
29320 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
29330 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
29340 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
29350 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
29360 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
29370 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
29380 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29390 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
293a0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
293b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
293c0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
293d0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
293e0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
293f0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
29400 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29410 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29420 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
29430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29440 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
29450 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29460 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
29470 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
29480 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29490 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
294a0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
294b0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
294c0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
294d0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
294e0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
294f0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
29500 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
29510 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
29520 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
29530 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
29540 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
29550 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
29560 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
29570 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
29580 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
29590 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
295a0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
295b0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
295c0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
295d0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
295e0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
295f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
29600 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
29610 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
29620 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
29630 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
29640 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
29650 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
29660 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
29670 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
29680 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
29690 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
296a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
296b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
296c0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
296d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
296e0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
296f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
29700 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
29710 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
29720 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
29730 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
29740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29750 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29770 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
29780 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
29790 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
297a0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
297b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
297c0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
297d0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
297e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
297f0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
29800 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
29810 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
29820 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
29830 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
29840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29850 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
29860 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
29870 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
29880 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
29890 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
298a0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
298b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
298c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
298d0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
298e0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
298f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29900 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
29910 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29920 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29930 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
29940 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29950 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
29960 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
29970 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
29980 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
29990 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
299a0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
299b0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
299c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
299d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
299e0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
299f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29a00 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
29a10 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
29a20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
29a30 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
29a40 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
29a50 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
29a60 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
29a70 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
29a80 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
29a90 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
29aa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29ab0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
29ac0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
29ad0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
29ae0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
29af0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
29b00 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
29b10 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
29b20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
29b30 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
29b40 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
29b50 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
29b60 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
29b70 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
29b80 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
29b90 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
29ba0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
29bb0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
29bc0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
29bd0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
29be0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
29bf0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
29c00 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
29c10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29c20 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
29c30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29c40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29c50 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
29c60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29c70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29c80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
29c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29ca0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
29cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
29cc0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
29cd0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29ce0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29cf0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
29d00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
29d10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
29d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
29d30 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
29d40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
29d50 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
29d60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29d70 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
29d80 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
29d90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29da0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29db0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29dc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
29dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
29de0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
29df0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
29e00 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
29e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e30 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
29e40 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
29e50 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
29e60 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
29e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29e80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
29e90 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
29ea0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
29eb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29ec0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
29ed0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
29ee0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
29ef0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
29f00 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a  d no errors or.*
29f10 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
29f20 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
29f30 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
29f40 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
29f50 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
29f60 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
29f70 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29f80 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
29f90 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
29fa0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
29fb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
29fc0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
29fd0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
29fe0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
29ff0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2a000 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a010 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a020 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2a030 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2a040 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2a050 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2a060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a070 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2a080 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2a090 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2a0a0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2a0b0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2a0c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a0d0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2a0e0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2a0f0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2a100 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2a110 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2a120 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2a130 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2a140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2a150 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2a160 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2a170 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2a180 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2a190 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2a1a0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2a1b0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2a1c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2a1d0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2a1e0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2a1f0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2a200 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2a210 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2a220 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2a230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a240 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2a250 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2a260 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2a270 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2a280 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2a290 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2a2a0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2a2b0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2a2c0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2a2d0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2a2e0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2a2f0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2a300 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2a310 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2a320 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a330 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2a340 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a350 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2a360 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2a370 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2a380 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2a390 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a3a0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2a3b0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2a3c0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2a3d0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2a3e0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2a3f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2a400 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2a410 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2a420 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2a430 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a440 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2a450 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2a460 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2a470 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2a480 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2a490 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2a4a0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2a4b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2a4c0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2a4d0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2a4e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a4f0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2a500 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2a510 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2a520 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2a530 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2a550 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2a560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a570 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2a580 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2a590 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2a5a0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2a5b0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2a5c0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2a5d0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2a5e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a5f0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2a600 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2a610 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2a620 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2a630 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2a640 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2a650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2a660 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2a670 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2a680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a690 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2a6a0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2a6b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2a6c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2a6d0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2a6e0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2a6f0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2a700 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a710 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2a720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a730 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2a740 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2a750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2a760 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2a770 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2a780 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2a790 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2a7a0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2a7b0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2a7c0 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2a7d0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2a7e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2a7f0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2a800 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2a810 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2a820 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2a830 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2a840 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2a850 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2a860 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2a870 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2a880 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2a890 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2a8a0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2a8b0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2a8c0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2a8d0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2a8e0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2a8f0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2a900 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2a910 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2a920 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2a930 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2a940 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2a950 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2a960 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2a970 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2a980 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2a990 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2a9a0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2a9b0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2a9c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2a9d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2a9e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2a9f0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2aa00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2aa10 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2aa20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2aa30 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2aa40 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2aa50 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2aa60 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2aa70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2aa80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2aa90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2aaa0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2aab0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2aac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2aad0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2aae0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2aaf0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2ab00 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2ab10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2ab20 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2ab30 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2ab40 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2ab50 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2ab60 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2ab70 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2ab80 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2ab90 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2aba0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2abb0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2abc0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2abd0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2abe0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2abf0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2ac00 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2ac10 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2ac20 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2ac30 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2ac40 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2ac50 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2ac60 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2ac70 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2ac80 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2ac90 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2aca0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2acb0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2acc0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2acd0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2ace0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2acf0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2ad00 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2ad10 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2ad20 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2ad30 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2ad40 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2ad50 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2ad60 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2ad70 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2ad80 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2ad90 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2ada0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2adb0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2adc0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2add0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2ade0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2adf0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2ae00 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2ae10 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2ae20 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2ae30 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2ae40 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2ae50 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2ae60 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2ae70 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2ae80 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2ae90 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2aea0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2aeb0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2aec0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2aed0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2aee0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2aef0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2af00 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2af10 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2af20 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2af30 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2af40 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2af50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2af60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2af70 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2af80 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2af90 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2afa0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2afb0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2afc0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2afd0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2afe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2aff0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2b000 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2b010 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2b020 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2b030 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2b040 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2b050 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2b060 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2b070 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2b080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2b090 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2b0a0 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2b0b0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2b0c0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2b0d0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2b0e0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2b0f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2b100 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2b110 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2b120 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2b130 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2b140 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2b150 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2b160 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2b170 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2b180 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2b190 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2b1a0 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2b1b0 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2b1c0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2b1d0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2b1e0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2b1f0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2b200 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2b210 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2b220 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2b230 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2b240 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2b250 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2b260 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2b270 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2b280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2b290 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2b2a0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2b2b0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2b2c0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2b2d0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2b2e0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2b2f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2b300 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2b310 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2b320 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2b330 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2b340 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2b350 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2b360 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2b370 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2b380 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2b390 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2b3a0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2b3b0 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2b3c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b3d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b3e0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2b3f0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2b400 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2b410 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2b420 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2b430 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2b440 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2b450 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2b460 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2b470 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2b480 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2b490 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2b4a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2b4b0 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2b4c0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2b4d0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2b4e0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2b4f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b500 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2b510 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2b520 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2b530 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2b540 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2b550 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2b560 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2b570 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2b580 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2b590 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2b5a0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2b5b0 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2b5c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b5d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b5e0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2b5f0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2b600 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2b610 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2b620 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2b630 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2b640 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2b650 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2b660 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2b670 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2b680 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2b690 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2b6a0 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2b6b0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2b6c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b6d0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2b6e0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2b6f0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2b700 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2b710 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2b720 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2b730 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2b740 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2b750 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2b760 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2b770 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2b780 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2b790 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2b7a0 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2b7b0 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2b7c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2b7d0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2b7e0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2b7f0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2b800 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2b810 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2b820 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2b830 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2b840 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2b850 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2b860 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2b870 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2b880 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2b890 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2b8a0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2b8b0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2b8c0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2b8d0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2b8e0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2b8f0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2b900 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2b910 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2b920 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b930 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2b940 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2b950 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b960 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2b970 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2b980 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2b990 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2b9a0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2b9b0 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2b9c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b9d0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2b9e0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2b9f0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2ba00 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2ba10 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ba20 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
2ba30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ba40 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2ba50 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2ba60 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2ba70 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2ba80 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2ba90 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2baa0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2bab0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2bac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2bad0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2bae0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2baf0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2bb00 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2bb10 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2bb20 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2bb30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2bb40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2bb50 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2bb60 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2bb70 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2bb80 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2bb90 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2bba0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2bbb0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2bbc0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2bbd0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2bbe0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2bbf0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2bc00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2bc10 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2bc20 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2bc30 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2bc40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bc50 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2bc60 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2bc70 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2bc80 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2bc90 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2bca0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2bcb0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2bcc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2bcd0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2bce0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2bcf0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2bd00 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2bd10 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2bd20 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2bd30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2bd40 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2bd50 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2bd60 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2bd70 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2bd80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2bd90 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2bda0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2bdb0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2bdc0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2bdd0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2bde0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2bdf0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2be00 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2be10 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2be20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2be30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2be40 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2be50 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2be60 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2be70 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2be80 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2be90 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2bea0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2beb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bec0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2bed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2bee0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2bef0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2bf00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2bf10 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2bf20 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2bf30 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2bf40 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2bf50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2bf60 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2bf70 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2bf80 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2bf90 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2bfa0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2bfb0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2bfc0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2bfd0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2bfe0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2bff0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2c000 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2c010 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2c020 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2c030 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2c040 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2c050 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2c060 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2c070 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2c080 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2c090 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2c0a0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2c0b0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
2c0c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2c0d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2c0e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c0f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2c100 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2c110 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2c120 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2c130 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2c140 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2c150 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2c160 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2c170 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2c180 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2c190 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2c1a0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2c1b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
2c1c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2c1d0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2c1e0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2c1f0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2c200 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2c210 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2c220 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2c230 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2c240 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2c250 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2c260 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2c270 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2c280 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2c290 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2c2a0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2c2b0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2c2c0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2c2d0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2c2e0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2c2f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2c300 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2c310 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2c320 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2c330 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2c340 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2c350 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2c360 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2c370 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2c380 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c390 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2c3a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c3b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2c3c0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2c3d0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2c3e0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2c3f0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2c400 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2c410 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2c420 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2c430 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2c440 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2c450 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c460 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2c470 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2c480 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c490 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2c4a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2c4b0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2c4c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2c4d0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2c4e0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2c4f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2c500 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2c510 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2c520 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2c530 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2c540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c550 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2c560 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2c570 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2c580 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c590 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2c5a0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2c5b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2c5c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2c5d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2c5e0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2c5f0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2c600 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2c610 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2c620 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2c630 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2c640 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2c650 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c660 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2c670 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2c680 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2c690 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2c6a0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2c6b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c6c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2c6d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2c6e0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2c6f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2c700 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2c710 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2c720 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2c730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c740 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2c750 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c760 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2c770 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2c780 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2c790 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2c7a0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2c7b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2c7c0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2c7d0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2c7e0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2c7f0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2c800 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2c810 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2c820 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2c830 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2c840 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2c850 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2c860 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2c870 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2c880 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2c890 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2c8a0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2c8b0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2c8c0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2c8d0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2c8e0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2c8f0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2c900 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2c910 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2c920 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2c930 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2c940 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2c950 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2c960 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2c970 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2c980 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2c990 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2c9a0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2c9b0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2c9c0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2c9d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2c9e0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2c9f0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2ca00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2ca10 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2ca20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2ca30 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2ca40 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2ca50 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2ca60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2ca70 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2ca80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2ca90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2caa0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2cab0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cac0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2cad0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cae0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2caf0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2cb00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2cb10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2cb20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2cb30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2cb40 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
2cb50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2cb60 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2cb70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2cb80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2cb90 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2cba0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2cbb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2cbc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cbd0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2cbe0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2cbf0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2cc00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2cc10 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2cc20 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2cc30 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2cc40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2cc50 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2cc60 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2cc70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2cc80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cc90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2cca0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ccb0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2ccc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ccd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cce0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2ccf0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2cd00 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2cd10 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2cd20 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2cd30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2cd40 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2cd50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2cd60 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2cd70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2cd80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cd90 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2cda0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2cdb0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2cdc0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2cdd0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2cde0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2cdf0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2ce00 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2ce10 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2ce20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2ce30 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2ce40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ce50 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2ce60 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2ce70 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2ce80 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2ce90 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2cea0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2ceb0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2cec0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2ced0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2cee0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2cef0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2cf00 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2cf10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2cf20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2cf30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2cf40 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2cf50 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2cf60 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2cf70 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2cf80 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2cf90 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2cfa0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2cfb0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2cfc0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2cfd0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2cfe0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2cff0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2d000 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2d010 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2d020 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2d030 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2d040 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2d050 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2d060 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2d070 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2d080 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2d090 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2d0a0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2d0b0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2d0c0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2d0d0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2d0e0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2d0f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2d100 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2d110 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2d120 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2d130 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2d140 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d150 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d160 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2d170 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2d180 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2d190 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2d1a0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2d1b0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2d1c0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2d1d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2d1e0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2d1f0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2d200 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d210 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2d220 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2d230 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2d240 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2d250 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2d260 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2d270 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2d280 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2d290 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2d2a0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2d2b0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2d2c0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2d2d0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2d2e0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2d2f0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2d300 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2d310 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2d320 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2d330 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2d340 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d350 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2d360 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2d370 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2d380 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2d390 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2d3a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2d3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2d3c0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2d3d0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2d3e0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2d3f0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2d400 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2d410 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2d420 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2d430 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2d440 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2d450 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2d460 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2d470 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2d480 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2d490 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2d4a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2d4b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2d4c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2d4d0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2d4e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2d4f0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2d500 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2d510 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2d520 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2d530 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2d540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d550 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2d560 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2d570 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2d580 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2d590 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2d5a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2d5b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d5c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2d5d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d5e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2d5f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2d600 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2d610 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2d620 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2d630 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2d640 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2d650 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d660 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2d670 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2d680 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d690 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2d6a0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2d6b0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2d6c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d6d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d6e0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2d6f0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2d700 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2d710 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d720 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2d730 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d740 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2d750 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2d760 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d770 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2d780 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2d790 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2d7a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2d7b0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2d7c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d7d0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2d7e0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2d7f0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2d800 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2d810 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2d820 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2d830 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2d840 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2d850 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2d860 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2d870 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
2d880 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2d890 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2d8a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2d8b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2d8c0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2d8d0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2d8e0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2d8f0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2d900 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2d910 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2d920 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2d930 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2d940 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2d950 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2d960 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2d970 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2d980 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2d990 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2d9a0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2d9b0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2d9c0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2d9d0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2d9e0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2d9f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2da00 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2da10 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2da20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2da30 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2da40 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2da50 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2da60 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2da70 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2da80 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2da90 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2daa0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2dab0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2dac0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2dad0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2dae0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2daf0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2db00 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2db10 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2db20 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2db30 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2db40 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
2db50 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2db60 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2db70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2db80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
2db90 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
2dba0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
2dbb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2dbc0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
2dbd0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
2dbe0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
2dbf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2dc00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
2dc10 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
2dc20 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
2dc30 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
2dc40 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
2dc50 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
2dc60 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
2dc70 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
2dc80 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
2dc90 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
2dca0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
2dcb0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
2dcc0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2dcd0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
2dce0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2dcf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
2dd00 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2dd10 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
2dd20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
2dd30 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
2dd40 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
2dd50 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
2dd60 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2dd70 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2dd80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dd90 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2dda0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2ddb0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2ddc0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2ddd0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2dde0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2ddf0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2de00 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
2de10 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
2de20 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2de30 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
2de40 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
2de50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2de60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
2de70 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
2de80 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
2de90 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2dea0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2deb0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2dec0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2ded0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2dee0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2def0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2df00 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2df10 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2df20 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2df30 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
2df40 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
2df50 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2df60 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
2df70 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2df80 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
2df90 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2dfa0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2dfb0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2dfc0 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
2dfd0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
2dfe0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
2dff0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2e000 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2e010 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2e020 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2e030 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2e040 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2e050 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2e060 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
2e070 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
2e080 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2e090 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2e0a0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2e0b0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2e0c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2e0d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2e0e0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2e0f0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2e100 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2e110 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2e120 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e130 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e140 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2e150 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2e160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2e170 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2e180 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2e190 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
2e1a0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
2e1b0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
2e1c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2e1d0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2e1e0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2e1f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2e200 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2e210 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2e220 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
2e230 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2e240 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2e250 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2e260 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2e270 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2e280 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2e290 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2e2a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2e2b0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2e2c0 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
2e2d0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2e2e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2e2f0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2e300 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2e310 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2e320 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2e330 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2e340 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2e350 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2e360 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2e370 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2e380 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2e390 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2e3a0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2e3b0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2e3c0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2e3d0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2e3e0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2e3f0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2e400 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2e410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2e420 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2e430 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2e440 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2e450 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2e460 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2e470 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2e480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e490 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2e4a0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2e4b0 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
2e4c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2e4d0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2e4e0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2e4f0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2e500 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2e510 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2e520 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
2e530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e540 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2e550 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e560 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
2e570 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2e580 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2e590 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2e5a0 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
2e5b0 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
2e5c0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
2e5d0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
2e5e0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
2e5f0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
2e600 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
2e610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e620 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
2e630 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
2e640 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
2e650 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2e660 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2e670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e680 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
2e690 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2e6a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
2e6b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
2e6c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2e6d0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
2e6e0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
2e6f0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
2e700 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2e710 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
2e720 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
2e730 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
2e740 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
2e750 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2e760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2e770 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
2e780 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
2e790 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2e7a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e7b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2e7c0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
2e7d0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
2e7e0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
2e7f0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
2e800 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2e810 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2e820 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2e830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2e840 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
2e850 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2e860 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
2e870 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e880 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2e890 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2e8a0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
2e8b0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
2e8c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2e8d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e8e0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2e8f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2e900 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
2e910 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
2e920 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
2e930 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
2e940 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
2e950 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
2e960 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
2e970 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
2e980 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
2e990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e9a0 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
2e9b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2e9c0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
2e9d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
2e9e0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
2e9f0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2ea00 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2ea10 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2ea20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ea30 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
2ea40 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
2ea50 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
2ea60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ea70 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
2ea80 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
2ea90 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
2eaa0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2eab0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2eac0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2ead0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2eae0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2eaf0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2eb00 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2eb10 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2eb20 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2eb30 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2eb40 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2eb50 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2eb60 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2eb70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2eb80 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
2eb90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2eba0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
2ebb0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2ebc0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
2ebd0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
2ebe0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
2ebf0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2ec00 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
2ec10 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
2ec20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ec30 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2ec40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ec50 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
2ec60 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
2ec70 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
2ec80 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2ec90 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
2eca0 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
2ecb0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2ecc0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
2ecd0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
2ece0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
2ecf0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
2ed00 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
2ed10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ed20 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
2ed30 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
2ed40 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
2ed50 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
2ed60 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
2ed70 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
2ed80 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
2ed90 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
2eda0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
2edb0 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
2edc0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2edd0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2ede0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2edf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ee00 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2ee10 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2ee20 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2ee30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ee40 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
2ee50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
2ee60 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2ee70 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
2ee80 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
2ee90 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
2eea0 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
2eeb0 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
2eec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2eed0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
2eee0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2eef0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2ef00 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2ef10 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
2ef20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
2ef30 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
2ef40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2ef50 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
2ef60 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2ef70 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2ef80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ef90 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2efa0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
2efb0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2efc0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2efd0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2efe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eff0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2f000 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2f010 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2f020 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2f030 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f040 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2f050 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2f060 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2f070 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2f080 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2f090 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2f0a0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
2f0b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2f0c0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2f0d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f0e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f0f0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
2f100 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f110 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
2f120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f130 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
2f140 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2f150 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
2f160 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f170 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
2f180 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
2f190 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
2f1a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f1b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f1c0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
2f1d0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
2f1e0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
2f1f0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
2f200 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
2f210 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
2f220 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2f230 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
2f240 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
2f250 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
2f260 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
2f270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
2f280 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
2f290 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2f2a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f2b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
2f2c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
2f2d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2f2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f2f0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2f300 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2f310 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2f320 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2f330 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2f340 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
2f350 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2f360 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
2f370 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2f380 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2f390 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2f3a0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2f3b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2f3c0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2f3d0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2f3e0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2f3f0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2f400 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f410 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2f420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2f430 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2f440 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
2f450 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2f460 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2f470 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2f480 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2f490 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f4a0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2f4b0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2f4c0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2f4d0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2f4e0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2f4f0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2f500 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
2f510 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2f520 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2f530 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2f540 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2f550 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2f560 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2f570 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
2f580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2f590 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2f5a0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2f5b0 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
2f5c0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
2f5d0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
2f5e0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
2f5f0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
2f600 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2f610 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
2f620 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
2f630 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
2f640 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2f650 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
2f660 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2f670 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2f680 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2f690 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2f6a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2f6b0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2f6c0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2f6d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2f6e0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2f6f0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2f700 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2f710 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2f720 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2f730 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2f740 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2f750 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f760 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2f770 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2f780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2f790 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2f7a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2f7b0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2f7c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f7d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f7e0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2f7f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f800 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f810 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2f820 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2f830 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
2f840 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2f850 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2f860 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2f870 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f880 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
2f890 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f8a0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
2f8b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
2f8c0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
2f8d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
2f8e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f8f0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
2f900 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2f910 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
2f920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f930 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2f940 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2f950 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2f960 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f970 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2f980 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2f990 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2f9a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f9b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2f9c0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2f9d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2f9e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2f9f0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2fa00 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2fa10 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
2fa20 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
2fa30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fa40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2fa50 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
2fa60 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2fa70 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
2fa80 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2fa90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2faa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2fab0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2fac0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2fad0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2fae0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2faf0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2fb00 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2fb10 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2fb20 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2fb30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2fb40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fb50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2fb60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fb70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2fb80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fb90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2fba0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2fbb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2fbc0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2fbd0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2fbe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fbf0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2fc00 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2fc10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2fc20 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2fc30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2fc40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2fc50 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2fc60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2fc70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2fc80 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2fc90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2fca0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2fcb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2fcc0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2fcd0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2fce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fcf0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2fd00 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2fd10 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2fd20 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2fd30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fd40 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2fd50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2fd60 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2fd70 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2fd80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fd90 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2fda0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2fdb0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2fdc0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2fdd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fde0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2fdf0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2fe00 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2fe10 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2fe20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2fe30 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2fe40 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2fe50 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2fe60 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2fe70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2fe80 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2fe90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fea0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2feb0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
2fec0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2fed0 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
2fee0 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
2fef0 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
2ff00 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
2ff10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ff20 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
2ff30 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2ff40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2ff50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2ff60 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
2ff70 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
2ff80 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ff90 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
2ffa0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ffb0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
2ffc0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
2ffd0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
2ffe0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
2fff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30000 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
30010 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
30020 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
30030 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
30040 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
30050 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
30060 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
30070 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
30080 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
30090 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
300a0 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
300b0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
300c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
300d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
300e0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
300f0 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
30100 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
30110 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
30120 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
30130 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
30140 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
30150 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
30160 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
30170 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
30180 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
30190 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
301a0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
301b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
301c0 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
301d0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
301e0 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
301f0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
30200 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
30210 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
30220 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
30230 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
30240 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
30250 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
30260 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
30270 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
30280 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
30290 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
302a0 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
302b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
302c0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
302d0 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
302e0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
302f0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30300 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
30310 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30320 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
30330 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
30340 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
30350 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
30360 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
30370 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
30380 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30390 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
303a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
303b0 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
303c0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
303d0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
303e0 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
303f0 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
30400 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
30410 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
30420 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
30430 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
30440 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
30450 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
30460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
30470 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
30480 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
30490 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
304a0 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
304b0 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
304c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
304d0 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
304e0 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
304f0 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
30500 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
30510 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
30520 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
30530 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
30540 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
30550 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
30560 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
30570 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
30580 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
30590 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
305a0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
305b0 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
305c0 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
305d0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
305e0 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
305f0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
30600 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
30610 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
30620 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
30630 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
30640 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
30650 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
30660 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
30670 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
30680 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
30690 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
306a0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
306b0 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
306c0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
306d0 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
306e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
306f0 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
30700 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
30710 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
30720 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
30730 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
30740 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
30750 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
30760 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
30770 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
30780 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
30790 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
307a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
307b0 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
307c0 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
307d0 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
307e0 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
307f0 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
30800 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
30810 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
30820 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
30830 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
30840 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
30850 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
30860 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
30870 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
30880 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
30890 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
308a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
308b0 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
308c0 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
308d0 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
308e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
308f0 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
30900 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
30910 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
30920 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
30930 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30940 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30950 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
30960 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
30970 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
30980 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
30990 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
309a0 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
309b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
309c0 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
309d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
309e0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
309f0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
30a00 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
30a10 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
30a20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
30a30 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
30a40 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
30a50 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
30a60 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
30a70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
30a80 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
30a90 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
30aa0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
30ab0 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
30ac0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
30ad0 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
30ae0 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
30af0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30b00 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
30b10 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
30b20 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
30b30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
30b40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
30b50 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
30b60 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
30b70 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
30b80 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
30b90 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
30ba0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
30bb0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
30bc0 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
30bd0 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
30be0 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
30bf0 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
30c00 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
30c10 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
30c20 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
30c30 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
30c40 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
30c50 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
30c60 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
30c70 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
30c80 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
30c90 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
30ca0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
30cb0 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
30cc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
30cd0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
30ce0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
30cf0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
30d00 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
30d10 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
30d20 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
30d30 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
30d40 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
30d50 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
30d60 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
30d70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
30d80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
30d90 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
30da0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30db0 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
30dc0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
30dd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
30de0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
30df0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
30e00 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
30e10 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
30e20 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
30e30 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
30e40 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
30e50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
30e60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
30e70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
30e80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
30e90 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
30ea0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
30eb0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
30ec0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
30ed0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
30ee0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
30ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
30f00 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
30f10 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
30f20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
30f30 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
30f40 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
30f50 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
30f60 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
30f70 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
30f80 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
30f90 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
30fa0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
30fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30fc0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
30fd0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
30fe0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
30ff0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
31000 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
31010 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
31020 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
31030 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
31040 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
31050 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
31060 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
31070 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
31080 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
31090 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
310a0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
310b0 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
310c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
310d0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
310e0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
310f0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
31100 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
31110 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
31120 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
31130 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
31140 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
31150 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
31160 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
31170 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
31180 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
31190 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
311a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
311b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
311c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
311d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
311e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
311f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
31200 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
31210 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
31220 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
31230 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
31240 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
31250 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
31260 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
31270 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
31280 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
31290 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
312a0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
312b0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
312c0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
312d0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
312e0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
312f0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
31300 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
31310 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31320 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
31330 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
31340 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
31350 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
31360 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
31370 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
31380 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
31390 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
313a0 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
313b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
313c0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
313d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
313e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
313f0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
31400 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
31410 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
31420 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
31430 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
31440 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
31450 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
31460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
31470 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
31480 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31490 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
314a0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
314b0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
314c0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
314d0 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
314e0 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
314f0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
31500 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
31510 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
31520 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
31530 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
31540 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
31550 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
31560 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
31570 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
31580 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
31590 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
315a0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
315b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
315c0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
315d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
315e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
315f0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
31600 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
31610 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
31620 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
31630 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
31640 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
31650 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
31660 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
31670 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
31680 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
31690 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
316a0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
316b0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
316c0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
316d0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
316e0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
316f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
31700 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
31710 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
31720 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
31730 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
31740 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
31750 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
31760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31770 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
31780 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
31790 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
317a0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
317b0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
317c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
317d0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
317e0 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
317f0 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
31800 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
31810 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
31820 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
31830 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
31840 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
31850 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
31860 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
31870 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
31880 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
31890 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
318a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
318b0 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
318c0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
318d0 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
318e0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
318f0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
31900 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
31910 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
31920 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
31930 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
31940 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
31950 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
31960 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
31970 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
31980 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
31990 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
319a0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
319b0 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
319c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
319d0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
319e0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
319f0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
31a00 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
31a10 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
31a20 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
31a30 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
31a40 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
31a50 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
31a60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
31a70 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
31a80 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
31a90 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
31aa0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
31ab0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
31ac0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
31ad0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
31ae0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
31af0 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
31b00 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
31b10 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
31b20 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
31b30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
31b40 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
31b50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
31b60 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
31b70 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
31b80 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
31b90 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
31ba0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
31bb0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
31bc0 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
31bd0 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
31be0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
31bf0 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
31c00 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
31c10 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
31c20 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
31c30 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
31c40 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
31c50 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
31c60 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
31c70 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
31c80 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
31c90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31ca0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
31cb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
31cc0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
31cd0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
31ce0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
31cf0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
31d00 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
31d10 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
31d20 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
31d30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
31d40 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
31d50 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
31d60 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
31d70 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
31d80 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
31d90 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
31da0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
31db0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
31dc0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
31dd0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
31de0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
31df0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31e00 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
31e10 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
31e20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
31e30 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
31e40 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
31e50 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
31e60 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
31e70 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
31e80 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
31e90 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
31ea0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
31eb0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
31ec0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
31ed0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
31ee0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
31ef0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
31f00 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
31f10 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
31f20 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
31f30 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
31f40 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
31f50 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
31f60 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
31f70 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
31f80 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
31f90 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
31fa0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
31fb0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
31fc0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
31fd0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
31fe0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
31ff0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
32000 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
32010 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
32020 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
32030 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
32040 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
32050 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
32060 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32070 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
32080 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
32090 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
320a0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
320b0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
320c0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
320d0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
320e0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
320f0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
32100 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
32110 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
32120 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
32130 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
32140 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
32150 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
32160 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
32170 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
32180 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
32190 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
321a0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
321b0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
321c0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
321d0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
321e0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
321f0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
32200 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
32210 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
32220 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
32230 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
32240 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
32250 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
32260 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
32270 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
32280 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
32290 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
322a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
322b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
322c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
322d0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
322e0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
322f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
32300 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
32310 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
32320 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
32330 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
32340 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
32350 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
32360 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
32370 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
32380 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
32390 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
323a0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
323b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
323c0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
323d0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
323e0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
323f0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
32400 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
32410 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
32420 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
32430 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
32440 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
32450 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
32460 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
32470 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
32480 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
32490 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
324a0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
324b0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
324c0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
324d0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
324e0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
324f0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
32500 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
32510 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
32520 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
32530 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
32540 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
32550 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
32560 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
32570 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
32580 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
32590 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
325a0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
325b0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
325c0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
325d0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
325e0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
325f0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
32600 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
32610 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
32620 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
32630 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
32640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32650 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
32660 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
32670 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
32680 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
32690 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
326a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
326b0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
326c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
326d0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
326e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
326f0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
32700 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
32710 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
32720 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
32730 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
32740 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
32750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
32760 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
32770 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
32780 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
32790 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
327a0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
327b0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
327c0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
327d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
327e0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
327f0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
32800 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
32810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
32820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32830 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
32840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32850 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
32860 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
32880 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
32890 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
328a0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
328b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
328c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
328d0 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
328e0 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
328f0 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
32900 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
32910 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
32920 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
32930 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
32940 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
32950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32960 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
32970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
32980 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
32990 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
329a0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
329b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
329c0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
329d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
329e0 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
329f0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
32a00 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
32a10 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
32a20 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
32a30 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
32a40 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
32a50 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
32a60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
32a70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
32a80 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
32a90 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
32aa0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
32ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32ac0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
32ad0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
32ae0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
32af0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32b00 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
32b10 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
32b20 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
32b30 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
32b40 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
32b50 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
32b60 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
32b70 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
32b80 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
32b90 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
32ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
32bb0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
32bc0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
32bd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
32be0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
32bf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
32c00 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
32c10 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
32c20 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
32c30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
32c40 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
32c50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
32c60 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
32c70 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
32c80 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
32c90 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
32ca0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
32cb0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
32cc0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
32cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32ce0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
32cf0 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
32d00 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
32d10 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
32d20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
32d30 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
32d40 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
32d50 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
32d60 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
32d70 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
32d80 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
32d90 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
32da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
32db0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
32dc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
32dd0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
32de0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
32df0 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
32e00 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
32e10 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
32e20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
32e30 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
32e40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32e50 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
32e60 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
32e70 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
32e80 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
32e90 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
32ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32eb0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
32ec0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
32ed0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
32ee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32ef0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
32f00 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
32f10 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
32f20 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
32f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
32f40 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
32f50 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
32f60 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
32f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
32f80 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
32f90 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
32fa0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
32fb0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
32fc0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
32fd0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
32fe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
32ff0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
33000 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
33010 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
33020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
33030 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
33040 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
33050 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
33060 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
33070 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
33080 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
33090 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
330a0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
330b0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
330c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
330d0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
330e0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
330f0 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
33100 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
33110 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
33120 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
33130 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
33140 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
33150 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
33160 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
33170 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
33180 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
33190 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
331a0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
331b0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
331c0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
331d0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
331e0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
331f0 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
33200 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
33210 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
33220 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
33230 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
33240 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
33250 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
33260 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
33270 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
33280 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
33290 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
332a0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
332b0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
332c0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
332d0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
332e0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
332f0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
33300 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
33310 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
33320 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
33330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33340 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
33350 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
33360 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
33370 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
33380 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
33390 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
333a0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
333b0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
333c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
333d0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
333e0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
333f0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
33400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33410 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
33420 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
33430 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
33440 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
33450 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
33460 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
33470 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
33480 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
33490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
334a0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
334b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
334c0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
334d0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
334e0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
334f0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
33500 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
33510 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
33520 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
33530 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
33540 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33560 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
33570 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
33580 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
33590 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
335a0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
335b0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
335c0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
335d0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
335e0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
335f0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
33600 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
33610 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
33620 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
33630 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
33640 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
33650 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
33660 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
33670 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
33680 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
33690 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
336a0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
336b0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
336c0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
336d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
336e0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
336f0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
33700 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
33710 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
33720 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
33730 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
33740 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
33750 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
33760 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
33770 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
33780 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
33790 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
337a0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
337b0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
337c0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
337d0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
337e0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
337f0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
33800 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
33810 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
33820 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
33830 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
33840 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
33850 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
33860 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
33870 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
33880 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
33890 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
338a0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
338b0 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
338c0 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
338d0 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
338e0 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
338f0 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
33900 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
33910 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
33920 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
33930 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
33940 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
33950 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
33960 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
33970 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
33980 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
33990 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
339a0 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
339b0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
339c0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
339d0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
339e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
339f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
33a00 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
33a10 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
33a20 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
33a30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
33a40 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
33a50 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
33a60 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
33a70 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
33a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
33a90 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
33aa0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
33ab0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
33ac0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
33ad0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
33ae0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
33af0 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
33b00 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
33b10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
33b20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
33b30 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
33b40 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
33b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
33b60 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
33b70 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
33b80 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
33b90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33ba0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
33bb0 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
33bc0 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
33bd0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
33be0 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
33bf0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
33c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33c10 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
33c20 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
33c30 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
33c40 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
33c50 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
33c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33c70 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
33c80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
33c90 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
33ca0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
33cb0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
33cc0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
33cd0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
33ce0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
33cf0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
33d00 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
33d10 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
33d20 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
33d30 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
33d40 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
33d50 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
33d60 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
33d70 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
33d80 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
33d90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
33da0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
33db0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
33dc0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
33dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
33de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
33df0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
33e00 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
33e10 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
33e20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
33e30 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
33e40 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
33e50 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
33e60 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
33e70 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
33e80 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
33e90 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
33ea0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
33eb0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
33ec0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
33ed0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
33ee0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
33ef0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
33f00 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
33f10 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
33f20 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
33f30 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
33f40 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
33f50 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
33f60 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
33f70 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
33f80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
33f90 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
33fa0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33fb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
33fc0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
33fd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33fe0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
33ff0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
34000 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
34010 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
34020 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
34030 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
34040 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
34050 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
34060 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
34070 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
34080 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
34090 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
340a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
340b0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
340c0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
340d0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
340e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
340f0 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
34100 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
34110 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
34120 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
34130 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
34140 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
34150 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
34160 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
34170 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
34180 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
34190 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
341a0 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
341b0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
341c0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
341d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
341e0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
341f0 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
34200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34210 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
34220 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
34230 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
34240 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
34250 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
34260 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
34270 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
34280 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
34290 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
342a0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
342b0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
342c0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
342d0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
342e0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
342f0 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
34300 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
34310 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
34320 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
34330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
34340 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
34350 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
34360 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
34370 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
34380 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
34390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
343a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
343b0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
343c0 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
343d0 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
343e0 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
343f0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
34400 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
34410 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  EMENT]..*/.int s
34420 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
34430 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
34440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
34450 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
34460 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
34470 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
34480 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
34490 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61  interface sets a
344a0 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68  nd/or queries th
344b0 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20  e.** soft limit 
344c0 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
344d0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
344e0 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
344f0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
34500 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73   ^SQLite strives
34510 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65   to keep heap me
34520 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e  mory utilization
34530 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
34540 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79  heap.** limit by
34550 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75   reducing the nu
34560 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65  mber of pages he
34570 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63  ld in the page c
34580 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20  ache.** as heap 
34590 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70  memory usages ap
345a0 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d  proaches the lim
345b0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74  it..** ^The soft
345c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22   heap limit is "
345d0 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76  soft" because ev
345e0 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65  en though SQLite
345f0 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79   strives to stay
34600 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69  .** below the li
34610 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63  mit, it will exc
34620 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61  eed the limit ra
34630 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61  ther than genera
34640 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45  te.** an [SQLITE
34650 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20  _NOMEM] error.  
34660 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
34670 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34680 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73  mit .** is advis
34690 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
346a0 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  ^The return valu
346b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  e from sqlite3_s
346c0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
346d0 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  () is the size o
346e0 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  f.** the soft he
346f0 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74  ap limit prior t
34700 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66  o the call.  ^If
34710 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
34720 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74  is negative.** t
34730 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73  hen no change is
34740 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66   made to the sof
34750 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48  t heap limit.  H
34760 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e  ence, the curren
34770 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
34780 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34790 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
347a0 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a  ed by invoking.*
347b0 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  * sqlite3_soft_h
347c0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69  eap_limit64() wi
347d0 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72  th a negative ar
347e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gument..**.** ^I
347f0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
34800 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68   is zero then th
34810 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
34820 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  t is disabled..*
34830 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20  *.** ^(The soft 
34840 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f  heap limit is no
34850 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68  t enforced in th
34860 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
34870 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f  entation.** if o
34880 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f  ne or more of fo
34890 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f  llowing conditio
348a0 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a  ns are true:.**.
348b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
348c0 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
348d0 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65  mit is set to ze
348e0 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f  ro..** <li> Memo
348f0 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73  ry accounting is
34900 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
34910 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
34920 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71   the.**      [sq
34930 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
34940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
34950 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61  STATUS],...) sta
34960 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61  rt-time option a
34970 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b  nd.**      the [
34980 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
34990 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c  EMSTATUS] compil
349a0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
349b0 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e  * <li> An altern
349c0 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65  ative page cache
349d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
349e0 69 73 20 73 70 65 63 69 66 69 65 64 20 75 73 69  is specified usi
349f0 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
34a00 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
34a10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
34a20 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e  E],...)..** <li>
34a30 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20   The page cache 
34a40 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69  allocates from i
34a50 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f  ts own memory po
34a60 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20  ol supplied.**  
34a70 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
34a80 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
34a90 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
34aa0 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68  ],...) rather th
34ab0 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20  an.**      from 
34ac0 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75  the heap..** </u
34ad0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e  l>)^.**.** Begin
34ae0 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
34af0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20   version 3.7.3, 
34b00 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34b10 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a  mit is enforced.
34b20 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
34b30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
34b40 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
34b50 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
34b60 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  MENT].** compile
34b70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
34b80 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b  invoked.  With [
34b90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
34ba0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
34bb0 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  ,.** the soft he
34bc0 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f  ap limit is enfo
34bd0 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65  rced on every me
34be0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  mory allocation.
34bf0 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51    Without.** [SQ
34c00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
34c10 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20  RY_MANAGEMENT], 
34c20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34c30 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f  mit is only enfo
34c40 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d  rced.** when mem
34c50 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
34c60 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63   by the page cac
34c70 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67  he.  Testing sug
34c80 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75  gests that becau
34c90 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63  se.** the page c
34ca0 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64  ache is the pred
34cb0 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75  ominate memory u
34cc0 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d  ser in SQLite, m
34cd0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
34ce0 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65  ons will achieve
34cf0 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68   adequate soft h
34d00 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63  eap limit enforc
34d10 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a  ement without.**
34d20 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c   the use of [SQL
34d30 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
34d40 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
34d50 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73  *.** The circums
34d60 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69  tances under whi
34d70 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  ch SQLite will e
34d80 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20  nforce the soft 
34d90 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a  heap limit may.*
34da0 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74  * changes in fut
34db0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
34dc0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74  SQLite..*/.sqlit
34dd0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
34de0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
34df0 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64(sqlite3_int64
34e00 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
34e10 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
34e20 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74   Soft Heap Limit
34e30 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45   Interface.** DE
34e40 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
34e50 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61  his is a depreca
34e60 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  ted version of t
34e70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
34e80 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
34e90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
34ea0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
34eb0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73  provided for his
34ec0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
34ed0 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20  ility.** only.  
34ee0 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  All new applicat
34ef0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20  ions should use 
34f00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
34f10 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
34f20 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  4()] interface r
34f30 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20  ather than this 
34f40 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44  one..*/.SQLITE_D
34f50 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
34f60 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
34f70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a  _limit(int N);..
34f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f90 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
34fa0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
34fb0 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
34fc0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
34fd0 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61  returns metadata
34fe0 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
34ff0 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
35000 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61  ecific.** databa
35010 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  se table accessi
35020 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64  ble using the [d
35030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35040 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61  on] handle.** pa
35050 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
35060 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  t function argum
35070 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35080 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
35090 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
350a0 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
350b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
350c0 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
350d0 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ion. ^The second
350e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
350f0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
35100 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
35110 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
35120 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74  temp", or an att
35130 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
35140 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
35150 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
35160 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69  e or NULL. ^If i
35170 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
35180 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
35190 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
351a0 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
351b0 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
351c0 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73  ame algorithm us
351d0 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
351e0 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20  se engine to.** 
351f0 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
35200 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
35210 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nces..**.** ^The
35220 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
35230 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
35240 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72  this function ar
35250 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20  e the table and 
35260 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f  column.** name o
35270 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  f the desired co
35280 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65  lumn, respective
35290 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74  ly. Neither of t
352a0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a  hese parameters.
352b0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
352c0 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20  **.** ^Metadata 
352d0 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
352e0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
352f0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
35300 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68  assed as the 5th
35310 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65  .** and subseque
35320 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
35330 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
35340 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72  ^Any of these ar
35350 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a  guments may be.*
35360 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  * NULL, in which
35370 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
35380 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
35390 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f  of metadata is o
353a0 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  mitted..**.** ^(
353b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
353c0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
353d0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50  ">.** <tr><th> P
353e0 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75  arameter <th> Ou
353f0 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68  tput<br>Type <th
35400 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a  >  Description.*
35410 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74  *.** <tr><td> 5t
35420 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61  h <td> const cha
35430 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70  r* <td> Data typ
35440 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74  e.** <tr><td> 6t
35450 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61  h <td> const cha
35460 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20  r* <td> Name of 
35470 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
35480 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74  n sequence.** <t
35490 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20  r><td> 7th <td> 
354a0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
354b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
354c0 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
354d0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72  onstraint.** <tr
354e0 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69  ><td> 8th <td> i
354f0 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
35500 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
35510 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
35520 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72  IMARY KEY.** <tr
35530 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69  ><td> 9th <td> i
35540 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
35550 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
35560 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  s [AUTOINCREMENT
35570 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ].** </table>.**
35580 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
35590 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
355a0 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
355b0 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
355c0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
355d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c   for the.** decl
355e0 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
355f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35600 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
35610 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
35620 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
35630 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74  SQLite API funct
35640 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
35650 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
35660 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
35670 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72   view, an [error
35680 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
35690 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
356a0 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
356b0 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
356c0 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
356d0 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54  " and an.** [INT
356e0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
356f0 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65  ] column has bee
35700 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  n explicitly dec
35710 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20  lared, then the 
35720 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65  output.** parame
35730 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72  ters are set for
35740 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20   the explicitly 
35750 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e  declared column.
35760 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 6e   ^(If there is n
35770 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
35780 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45  declared [INTEGE
35790 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
357a0 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
357b0 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65  output.** parame
357c0 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
357d0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
357e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61  pre>.**     data
357f0 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22   type: "INTEGER"
35800 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f  .**     collatio
35810 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e  n sequence: "BIN
35820 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20  ARY".**     not 
35830 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70  null: 0.**     p
35840 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a  rimary key: 1.**
35850 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d       auto increm
35860 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e  ent: 0.** </pre>
35870 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
35880 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
35890 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
358a0 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
358b0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
358c0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
358d0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
358e0 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
358f0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
35900 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
35910 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
35920 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
35930 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
35940 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c   error message l
35950 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64  eft.** in the [d
35960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35970 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69  on] (to be retri
35980 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
35990 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a  e3_errmsg()).)^.
359a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20  **.** ^This API 
359b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
359c0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
359d0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
359e0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
359f0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
35a00 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
35a10 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
35a20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
35a30 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
35a40 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
35a50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35a60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35a70 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
35a80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
35a90 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
35aa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
35ab0 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
35ac0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
35ad0 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
35ae0 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
35af0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
35b00 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
35b10 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
35b20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
35b30 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
35b40 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
35b50 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
35b60 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
35b70 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
35b80 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
35b90 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
35ba0 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
35bb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
35bc0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
35bd0 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
35be0 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
35bf0 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
35c00 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
35c10 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
35c20 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
35c30 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
35c40 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
35c50 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
35c60 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
35c70 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
35c80 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
35c90 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
35ca0 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  xtension.**.** ^
35cb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c  This interface l
35cc0 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65  oads an SQLite e
35cd0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
35ce0 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20   from the named 
35cf0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  file..**.** ^The
35d00 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
35d10 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
35d20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
35d30 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74  load an.** SQLit
35d40 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
35d50 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e  ary contained in
35d60 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e   the file zFile.
35d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72  .**.** ^The entr
35d80 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63  y point is zProc
35d90 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20  ..** ^zProc may 
35da0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
35db0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
35dc0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
35dd0 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22  ** defaults to "
35de0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f  sqlite3_extensio
35df0 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65  n_init"..** ^The
35e00 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
35e10 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
35e20 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ace returns.** [
35e30 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
35e40 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54  ccess and [SQLIT
35e50 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65  E_ERROR] if some
35e60 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
35e70 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  ..** ^If an erro
35e80 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
35e90 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
35ea0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  then the.** [sql
35eb0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
35ec0 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
35ed0 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74   shall attempt t
35ee0 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72  o.** fill *pzErr
35ef0 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d  Msg with error m
35f00 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
35f10 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
35f20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
35f30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35f40 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  . The calling fu
35f50 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  nction.** should
35f60 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72   free this memor
35f70 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  y by calling [sq
35f80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
35f90 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
35fa0 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
35fb0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
35fc0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
35fd0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
35fe0 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  )] prior to call
35ff0 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a  ing this API,.**
36000 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
36010 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ror will be retu
36020 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rned..**.** See 
36030 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65  also the [load_e
36040 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66  xtension() SQL f
36050 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74  unction]..*/.int
36060 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
36070 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
36080 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36090 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
360a0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
360b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
360c0 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
360d0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
360e0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
360f0 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
36100 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
36110 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
36120 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
36130 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
36140 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
36150 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
36160 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
36170 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
36180 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
36190 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
361a0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
361b0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
361c0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
361d0 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74  **.** ^So as not
361e0 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
361f0 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
36200 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
36210 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
36220 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
36230 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
36240 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
36250 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
36260 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
36270 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
36280 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
36290 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
362a0 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73  lowing API.** is
362b0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
362c0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
362d0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
362e0 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
362f0 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  d off..**.** ^Ex
36300 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
36310 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
36320 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  t. See ticket #1
36330 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68  863..** ^Call th
36340 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  e sqlite3_enable
36350 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
36360 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f  ) routine with o
36370 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75  noff==1.** to tu
36380 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  rn extension loa
36390 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c  ding on and call
363a0 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
363b0 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20  0 to turn.** it 
363c0 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
363d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
363e0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
363f0 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
36400 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
36410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
36420 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
36430 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e  d Statically Lin
36440 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a  ked Extensions.*
36450 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
36460 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
36470 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75  xEntryPoint() fu
36480 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
36490 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68  oked for.** each
364a0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
364b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
364c0 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
364d0 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68   idea here is th
364e0 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e  at.** xEntryPoin
364f0 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79  t() is the entry
36500 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61   point for a sta
36510 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53  tically linked S
36520 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a  QLite extension.
36530 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65  ** that is to be
36540 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c   automatically l
36550 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e  oaded into all n
36560 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
36570 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ections..**.** ^
36580 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65  (Even though the
36590 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74   function protot
365a0 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78  ype shows that x
365b0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b  EntryPoint() tak
365c0 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e  es.** no argumen
365d0 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76  ts and returns v
365e0 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f  oid, SQLite invo
365f0 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  kes xEntryPoint(
36600 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20  ) with three.** 
36610 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78  arguments and ex
36620 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65  pects and intege
36630 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 74  r result as if t
36640 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  he signature of 
36650 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69  the.** entry poi
36660 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c  nt where as foll
36670 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
36680 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
36690 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74  &nbsp;  int xEnt
366a0 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73  ryPoint(.** &nbs
366b0 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64  p;    sqlite3 *d
366c0 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  b,.** &nbsp;    
366d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45  const char **pzE
366e0 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b  rrMsg,.** &nbsp;
366f0 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74      const struct
36700 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
36710 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a  tines *pThunk.**
36720 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c   &nbsp;  );.** <
36730 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
36740 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  e>)^.**.** If th
36750 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f  e xEntryPoint ro
36760 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73  utine encounters
36770 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68   an error, it sh
36780 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72  ould make *pzErr
36790 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  Msg.** point to 
367a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
367b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62  rror message (ob
367c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
367d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29  ite3_mprintf()])
367e0 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61  .** and return a
367f0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
36800 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51  rror code].  ^SQ
36810 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 61  Lite ensures tha
36820 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69  t *pzErrMsg.** i
36830 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61  s NULL before ca
36840 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79  lling the xEntry
36850 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74  Point().  ^SQLit
36860 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  e will invoke.**
36870 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
36880 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61  ] on *pzErrMsg a
36890 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74  fter xEntryPoint
368a0 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66  () returns.  ^If
368b0 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f   any.** xEntryPo
368c0 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e  int() returns an
368d0 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c   error, the [sql
368e0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
368f0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
36900 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
36910 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c  _open_v2()] call
36920 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
36930 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
36940 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a   will fail..**.*
36950 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
36960 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
36970 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74  n(X) with an ent
36980 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20  ry point X that 
36990 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e  is already.** on
369a0 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74   the list of aut
369b0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
369c0 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  s is a harmless 
369d0 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79  no-op. ^No entry
369e0 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62   point.** will b
369f0 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68  e called more th
36a00 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  an once for each
36a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36a20 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65  tion that is ope
36a30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ned..**.** See a
36a40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65  lso: [sqlite3_re
36a50 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
36a60 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  on()]..*/.int sq
36a70 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
36a80 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74  sion(void (*xEnt
36a90 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b  ryPoint)(void));
36aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36ab0 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
36ac0 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
36ad0 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ing.**.** ^This 
36ae0 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62 6c  interface disabl
36af0 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63  es all automatic
36b00 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76   extensions prev
36b10 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74  iously.** regist
36b20 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
36b30 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
36b40 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73  on()]..*/.void s
36b50 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
36b60 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
36b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
36b80 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
36b90 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
36ba0 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
36bb0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
36bc0 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
36bd0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
36be0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
36bf0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
36c00 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
36c10 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
36c20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
36c30 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
36c40 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
36c50 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
36c60 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
36c70 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
36c80 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
36c90 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
36ca0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
36cb0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
36cc0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
36cd0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
36ce0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
36cf0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
36d00 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
36d10 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
36d20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36d30 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
36d40 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
36d50 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36d60 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
36d70 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
36d80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36d90 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
36da0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
36db0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
36dc0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
36dd0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
36de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36df0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
36e00 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
36e10 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
36e20 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
36e30 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  module}.**.** Th
36e40 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f  is structure, so
36e50 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61  metimes called a
36e60 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   "virtual table 
36e70 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66  module", .** def
36e80 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65  ines the impleme
36e90 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69  ntation of a [vi
36ea0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20  rtual tables].  
36eb0 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
36ec0 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74  re consists most
36ed0 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
36ee0 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
36ef0 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74  .** ^A virtual t
36f00 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63  able module is c
36f10 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e  reated by fillin
36f20 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e  g in a persisten
36f30 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  t.** instance of
36f40 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
36f50 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f  and passing a po
36f60 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  inter to that in
36f70 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71  stance.** to [sq
36f80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36f90 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ule()] or [sqlit
36fa0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
36fb0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
36fc0 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
36fd0 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
36fe0 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
36ff0 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
37000 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
37010 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
37020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
37030 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
37040 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
37050 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
37060 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
37070 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
37080 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
37090 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
370a0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
370b0 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
370c0 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
370d0 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
370e0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
370f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
37100 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
37110 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
37120 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37130 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
37140 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
37150 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
37160 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
37170 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
37180 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
37190 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
371a0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
371b0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
371c0 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
371d0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
371e0 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
371f0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
37200 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
37210 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
37220 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
37230 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
37240 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
37250 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
37260 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
37270 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
37280 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
37290 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
372a0 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
372b0 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
372c0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
372d0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
372e0 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
372f0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
37300 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
37310 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
37320 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
37330 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
37340 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
37350 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
37360 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37370 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
37380 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
37390 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
373a0 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
373b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
373c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
373d0 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
373e0 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
373f0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
37400 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
37410 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
37420 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
37430 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
37440 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
37450 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
37460 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
37470 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37480 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
37490 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
374a0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
374b0 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
374c0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
374d0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
374e0 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
374f0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
37500 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
37510 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37520 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
37530 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
37540 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
37550 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
37560 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
37570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
37580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
37590 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
375a0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
375b0 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
375c0 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
375d0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
375e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
375f0 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  /* The method
37600 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
37610 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
37620 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20 6f 62  sqlite_module ob
37630 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20 20 2a  ject. Those .  *
37640 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  * below are for 
37650 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 67 72  version 2 and gr
37660 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e 74 20  eater. */.  int 
37670 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73 71  (*xSavepoint)(sq
37680 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37690 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  b, int);.  int (
376a0 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c 69 74  *xRelease)(sqlit
376b0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
376c0 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
376d0 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74  ollbackTo)(sqlit
376e0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
376f0 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  int);.};../*.** 
37700 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
37710 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
37720 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
37730 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
37740 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a  3_index_info.**.
37750 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
37760 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
37770 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
37780 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
37790 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20  d as part.** of 
377a0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
377b0 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  le] interface to
377c0 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
377d0 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
377e0 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
377f0 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49  from the [xBestI
37800 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20  ndex].** method 
37810 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
37820 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68  ble module].  Th
37830 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a  e fields under *
37840 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68  *Inputs** are th
37850 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78  e.** inputs to x
37860 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72  BestIndex and ar
37870 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42  e read-only.  xB
37880 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73  estIndex inserts
37890 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20   its.** results 
378a0 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75  into the **Outpu
378b0 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a  ts** fields..**.
378c0 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72  ** ^(The aConstr
378d0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
378e0 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
378f0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
37900 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a   the form:.**.**
37910 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c   <blockquote>col
37920 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f  umn OP expr</blo
37930 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77  ckquote>.**.** w
37940 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c  here OP is =, &l
37950 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c  t;, &lt;=, &gt;,
37960 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28   or &gt;=.)^  ^(
37970 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f  The particular o
37980 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74  perator is.** st
37990 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61  ored in aConstra
379a0 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f  int[].op using o
379b0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51  ne of the.** [SQ
379c0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
379d0 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54  RAINT_EQ | SQLIT
379e0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
379f0 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a  NT_ values].)^.*
37a00 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66  * ^(The index of
37a10 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
37a20 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e  tored in.** aCon
37a30 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
37a40 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61  n.)^  ^(aConstra
37a50 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
37a60 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
37a70 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
37a80 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
37a90 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
37aa0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
37ab0 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
37ac0 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
37ad0 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a  it cannot.)^.**.
37ae0 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65  ** ^The optimize
37af0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
37b00 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
37b10 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
37b20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
37b30 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
37b40 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
37b50 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
37b60 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
37b70 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
37b80 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
37b90 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
37ba0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
37bb0 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e  s possible..** ^
37bc0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
37bd0 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
37be0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
37bf0 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65  e terms that are
37c00 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20  .** relevant to 
37c10 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
37c20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
37c30 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
37c40 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  * ^Information a
37c50 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
37c60 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
37c70 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
37c80 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20  ..** ^Each term 
37c90 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
37ca0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
37cb0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
37cc0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  use..**.** The [
37cd0 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68  xBestIndex] meth
37ce0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
37cf0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
37d00 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
37d10 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
37d20 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
37d30 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e  s to xFilter.  ^
37d40 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
37d50 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
37d60 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
37d70 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
37d80 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
37d90 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
37da0 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
37db0 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
37dc0 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20   in argv.  ^(If 
37dd0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
37de0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
37df0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
37e00 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
37e10 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
37e20 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
37e30 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
37e40 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
37e50 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
37e60 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e.)^.**.** ^The 
37e70 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
37e80 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
37e90 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
37ea0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46   into the.** [xF
37eb0 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a  ilter] method..*
37ec0 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  * ^[sqlite3_free
37ed0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
37ee0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
37ef0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65  d only if.** nee
37f00 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
37f10 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   true..**.** ^Th
37f20 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
37f30 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
37f40 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
37f50 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
37f60 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
37f70 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
37f80 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
37f90 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
37fa0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
37fb0 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
37fc0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
37fd0 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74  .** ^The estimat
37fe0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
37ff0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
38000 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
38010 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
38020 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
38030 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
38040 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
38050 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
38060 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
38070 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
38080 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
38090 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
380a0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
380b0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
380c0 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
380d0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
380e0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
380f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
38100 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
38110 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
38120 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
38130 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
38140 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
38150 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
38160 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
38170 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
38180 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
38190 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
381a0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
381b0 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
381c0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
381d0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
381e0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
381f0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
38200 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
38210 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
38220 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
38230 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
38240 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
38250 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
38260 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
38270 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
38280 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
38290 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
382a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
382b0 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
382c0 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
382d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
382e0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
382f0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
38300 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
38310 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
38320 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
38330 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
38340 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
38350 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
38360 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
38370 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
38380 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
38390 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
383a0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
383b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
383c0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
383d0 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
383e0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
383f0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
38400 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
38410 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
38420 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
38430 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
38440 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
38450 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
38460 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
38470 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
38480 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
38490 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
384a0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
384b0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
384c0 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
384d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
384e0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
384f0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
38500 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
38510 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
38520 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
38530 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
38540 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
38550 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
38560 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
38570 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
38580 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
38590 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
385a0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
385b0 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
385c0 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
385d0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
385e0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
385f0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
38600 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
38610 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
38620 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
38630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38640 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
38650 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 61  Constraint Opera
38660 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  tor Codes.**.** 
38670 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64 65 66  These macros def
38680 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 64  ined the allowed
38690 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 0a   values for the.
386a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65  ** [sqlite3_inde
386b0 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61  x_info].aConstra
386c0 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20  int[].op field. 
386d0 20 45 61 63 68 20 76 61 6c 75 65 20 72 65 70 72   Each value repr
386e0 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65  esents.** an ope
386f0 72 61 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  rator that is pa
38700 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 69  rt of a constrai
38710 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65 20 77  nt term in the w
38720 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a  HERE clause of.*
38730 2a 20 61 20 71 75 65 72 79 20 74 68 61 74 20 75  * a query that u
38740 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c 20 74  ses a [virtual t
38750 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  able]..*/.#defin
38760 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
38770 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20  ONSTRAINT_EQ    
38780 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
38790 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
387a0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e  T_GT    4.#defin
387b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
387c0 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
387d0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
387e0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
387f0 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69  T_LT    16.#defi
38800 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
38810 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20  CONSTRAINT_GE   
38820 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
38830 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
38840 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a  INT_MATCH 64../*
38850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20