/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact c0ebc53056fd99590dec4cb4bd60a0787098ff18:


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: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **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 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 73  delete opertions
86e0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
86f0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8700: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8710: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8720: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8730: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8740: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8750: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8760: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8770: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8780: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8790: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
87a0: 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73 20  those to values 
87b0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
87c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
87d0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
87e0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
87f0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
8800: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
8810: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8820: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
8830: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
8840: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
8850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
8860: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
8870: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
8880: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
8890: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
88a0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
88b0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
88c0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
88d0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
88e0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
88f0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
8900: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8910: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
8920: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
8930: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
8940: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
8950: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
8960: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
8970: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
8980: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
8990: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
89a0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
89b0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
89c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
89d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
89e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
89f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
8a00: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
8a10: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
8a20: 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73 65  te AHead Log] se
8a30: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
8a40: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
8a50: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
8a60: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
8a70: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
8a80: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
8a90: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
8aa0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
8ab0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
8ac0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
8ad0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
8ae0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
8af0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
8b00: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
8b10: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
8b20: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
8b30: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
8b40: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
8b50: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
8b60: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
8b70: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
8b80: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
8b90: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
8ba0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8bc0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
8bd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8be0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
8bf0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
8c00: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
8c10: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
8c20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
8c30: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
8c40: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
8c50: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
8c60: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c70: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
8c80: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
8c90: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
8ca0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
8cb0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
8cc0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
8cd0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
8ce0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
8cf0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
8d00: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
8d10: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
8d20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
8d30: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
8d40: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
8d50: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 20 0a  ce setting..** .
8d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8d70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8d80: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
8d90: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
8da0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8db0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
8dc0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
8dd0: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
8de0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
8df0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
8e00: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
8e10: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8e20: 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69  T        5.#defi
8e30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8e40: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
8e50: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
8e60: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8e70: 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69  NTER     7.#defi
8e80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8e90: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
8ea0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
8eb0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
8ec0: 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69  _RETRY   9.#defi
8ed0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8ee0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
8ef0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
8f00: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
8f10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
8f20: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
8f30: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
8f40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
8f50: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
8f60: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
8f70: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
8f80: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
8f90: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
8fa0: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
8fb0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
8fc0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
8fd0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
8fe0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
8ff0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
9000: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
9010: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
9020: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
9030: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
9040: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
9050: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
9060: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
9070: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
9080: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
9090: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
90a0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
90b0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
90c0: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
90d0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
90e0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
90f0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
9100: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
9110: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
9120: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
9130: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
9140: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
9150: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
9160: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
9170: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
9180: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
9190: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
91a0: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
91b0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
91c0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
91d0: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
91e0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
91f0: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
9200: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
9210: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
9220: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9230: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
9240: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
9250: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
9260: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
9270: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
9280: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
9290: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
92a0: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
92b0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
92c0: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
92d0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
92e0: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
92f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
9300: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
9310: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
9320: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
9330: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
9340: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
9350: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
9360: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
9370: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
9380: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
9390: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
93a0: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
93b0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
93c0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
93d0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
93e0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
93f0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
9400: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
9410: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
9420: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
9430: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
9440: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
9450: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
9460: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
9470: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
9480: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
9490: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
94a0: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
94b0: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
94c0: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
94d0: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
94e0: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
94f0: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
9500: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
9510: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
9520: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
9530: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
9540: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
9550: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
9560: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
9570: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
9580: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
9590: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
95a0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
95b0: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
95c0: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
95d0: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
95e0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
95f0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
9600: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
9610: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
9620: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
9630: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
9640: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
9650: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
9660: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
9670: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
9680: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
9690: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
96a0: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
96b0: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
96c0: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
96d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
96e0: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
96f0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
9700: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
9710: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
9720: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
9730: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
9740: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
9750: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
9760: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
9770: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
9780: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
9790: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
97a0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
97b0: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
97c0: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
97d0: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
97e0: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
97f0: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
9800: 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 10 alphanumeri
9810: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
9820: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
9830: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
9840: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
9850: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
9860: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
9870: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
9880: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
9890: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
98a0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
98b0: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
98c0: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
98d0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
98e0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
98f0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
9900: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
9910: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
9920: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
9930: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
9940: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
9950: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
9960: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
9970: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
9980: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
9990: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
99a0: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
99b0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
99c0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
99d0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
99e0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
99f0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
9a00: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
9a10: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
9a20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9a30: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
9a40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9a50: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
9a60: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
9a70: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
9a80: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9a90: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
9aa0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
9ab0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
9ac0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
9ad0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
9ae0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
9af0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
9b00: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
9b10: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
9b20: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
9b30: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
9b40: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
9b50: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
9b60: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
9b70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
9b80: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
9b90: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
9ba0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
9bb0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
9bc0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
9bd0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
9be0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
9bf0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
9c00: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
9c10: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
9c20: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
9c30: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
9c40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9c50: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
9c60: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
9c70: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9c80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
9c90: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
9ca0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
9cb0: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
9cc0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9cd0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
9ce0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9cf0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
9d00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9d10: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
9d20: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
9d30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
9d40: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
9d50: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
9d60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
9d70: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
9d80: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
9d90: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
9da0: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
9db0: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
9dc0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
9dd0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
9de0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
9df0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
9e00: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
9e10: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
9e20: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
9e30: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
9e40: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
9e50: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
9e60: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
9e70: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
9e80: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
9e90: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
9ea0: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
9eb0: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
9ec0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
9ed0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
9ee0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
9ef0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
9f00: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
9f10: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
9f20: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
9f30: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
9f40: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
9f50: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
9f60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
9f70: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
9f80: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
9f90: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
9fa0: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
9fb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
9fc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9fd0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
9fe0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
9ff0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
a000: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
a010: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a020: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
a030: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
a040: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
a050: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
a060: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
a070: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
a080: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
a090: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
a0a0: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
a0b0: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
a0c0: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
a0d0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
a0e0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
a0f0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
a100: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
a110: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
a120: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
a130: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
a140: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
a150: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
a160: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
a170: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
a180: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
a190: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
a1a0: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
a1b0: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
a1c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a1d0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
a1e0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
a1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
a200: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
a210: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
a220: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
a230: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
a240: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
a250: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
a260: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
a270: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
a280: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
a290: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
a2a0: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
a2b0: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
a2c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
a2d0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
a2e0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
a2f0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
a300: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
a310: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
a320: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
a330: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
a340: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
a350: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
a360: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
a370: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
a380: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
a390: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
a3a0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
a3b0: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
a3c0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
a3d0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
a3e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
a3f0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
a400: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
a410: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
a420: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
a430: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
a440: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
a450: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
a460: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
a470: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
a480: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
a490: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
a4a0: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
a4b0: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
a4c0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
a4d0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
a4e0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
a4f0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
a500: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
a510: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
a520: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
a530: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
a540: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
a550: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
a560: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
a570: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
a580: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
a590: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
a5a0: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
a5b0: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
a5c0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
a5d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
a5e0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
a5f0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
a600: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
a610: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
a620: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
a630: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
a640: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
a650: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
a660: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
a670: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
a680: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
a690: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
a6a0: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
a6b0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
a6c0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
a6d0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
a6e0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
a6f0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
a700: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
a710: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
a720: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
a730: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
a740: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
a750: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
a760: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
a770: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
a780: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
a790: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
a7a0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
a7b0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
a7c0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
a7d0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
a7e0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
a7f0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
a800: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
a810: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
a820: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
a830: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
a840: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
a850: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
a860: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
a870: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
a880: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
a890: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
a8a0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
a8b0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
a8c0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
a8d0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
a8e0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
a8f0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
a900: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
a910: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
a920: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
a930: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
a940: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
a950: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
a960: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
a970: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
a980: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
a990: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
a9a0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
a9b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
a9c0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
a9d0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a9e0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
a9f0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
aa00: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
aa10: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
aa20: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
aa30: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
aa40: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
aa50: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
aa60: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
aa70: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
aa80: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
aa90: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
aaa0: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
aab0: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
aac0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
aad0: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
aae0: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
aaf0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
ab00: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ab10: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
ab20: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab30: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
ab40: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
ab50: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
ab60: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
ab70: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
ab80: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
ab90: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
aba0: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
abb0: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
abc0: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
abd0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
abe0: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
abf0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
ac00: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
ac10: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
ac20: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
ac30: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
ac40: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
ac50: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
ac60: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
ac70: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
ac80: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
ac90: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
aca0: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
acb0: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
acc0: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
acd0: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
ace0: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
acf0: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
ad00: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
ad10: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
ad20: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
ad30: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
ad40: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
ad50: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
ad60: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
ad70: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
ad80: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
ad90: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
ada0: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
adb0: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
adc0: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
add0: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
ade0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
adf0: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
ae00: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
ae10: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
ae20: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
ae30: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
ae40: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
ae50: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
ae60: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
ae70: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
ae80: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
ae90: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
aea0: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
aeb0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
aec0: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
aed0: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
aee0: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
aef0: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
af00: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
af10: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
af20: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
af30: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
af40: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
af50: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
af60: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
af70: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
af80: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
af90: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
afa0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
afb0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
afc0: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
afd0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
afe0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
aff0: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
b000: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
b010: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
b020: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
b030: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
b040: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
b050: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
b060: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
b070: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
b080: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
b090: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
b0a0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
b0b0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
b0c0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
b0d0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
b0e0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
b0f0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
b100: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
b110: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
b120: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b130: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
b140: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
b150: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
b160: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
b170: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
b180: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
b190: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
b1a0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
b1b0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
b1c0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
b1d0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
b1e0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
b1f0: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
b200: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
b210: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
b220: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
b230: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
b240: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
b250: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
b260: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
b270: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
b280: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
b290: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
b2a0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
b2b0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
b2c0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
b2d0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
b2e0: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
b2f0: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
b300: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
b310: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
b320: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
b330: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
b340: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
b350: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
b360: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
b370: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
b380: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
b390: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
b3a0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
b3b0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
b3c0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
b3d0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
b3e0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
b3f0: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
b400: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
b410: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b420: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
b430: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
b440: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
b450: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
b460: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
b470: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
b480: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
b490: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
b4a0: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
b4b0: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
b4c0: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
b4d0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
b4e0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
b4f0: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
b500: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
b510: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
b520: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
b530: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
b540: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
b550: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
b560: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
b570: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b580: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
b590: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
b5a0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
b5b0: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
b5c0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
b5d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b5e0: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
b5f0: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
b600: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
b610: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b620: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
b630: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b640: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b650: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
b660: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
b670: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
b680: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
b690: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
b6a0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
b6b0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
b6c0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
b6d0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
b6e0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
b6f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b700: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
b710: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
b720: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
b730: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
b740: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
b750: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
b760: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
b770: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
b780: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
b790: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
b7a0: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
b7b0: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
b7c0: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
b7d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
b7e0: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
b7f0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
b800: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
b810: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
b820: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
b830: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
b840: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
b850: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b860: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
b870: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
b880: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
b890: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
b8a0: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
b8b0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
b8c0: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
b8d0: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
b8e0: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
b8f0: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
b900: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
b910: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
b920: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b930: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
b940: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
b950: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
b960: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
b970: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
b980: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
b990: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
b9a0: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
b9b0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
b9c0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
b9d0: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
b9e0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
b9f0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
ba00: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
ba10: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
ba20: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
ba30: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
ba40: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
ba50: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
ba60: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
ba70: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
ba80: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
ba90: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
baa0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
bab0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
bac0: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
bad0: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
bae0: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
baf0: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
bb00: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
bb10: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
bb20: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
bb30: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
bb40: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
bb50: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
bb60: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
bb70: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
bb80: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
bb90: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
bba0: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
bbb0: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
bbc0: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
bbd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
bbe0: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
bbf0: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
bc00: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
bc10: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
bc20: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
bc30: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
bc40: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
bc50: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
bc60: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
bc70: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
bc80: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
bc90: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
bca0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
bcb0: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
bcc0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
bcd0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
bce0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
bcf0: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
bd00: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
bd10: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
bd20: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
bd30: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
bd40: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
bd50: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
bd60: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
bd70: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
bd80: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
bd90: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
bda0: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
bdb0: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
bdc0: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
bdd0: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
bde0: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
bdf0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
be00: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
be10: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
be20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
be30: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
be40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
be50: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
be60: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
be70: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
be80: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
be90: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
bea0: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
beb0: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
bec0: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
bed0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
bee0: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
bef0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
bf00: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
bf10: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
bf20: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
bf30: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
bf40: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
bf50: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
bf60: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
bf70: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
bf80: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
bf90: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
bfa0: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
bfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
bfc0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
bfd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bfe0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
bff0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
c000: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
c010: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
c020: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
c030: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
c040: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
c050: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c060: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
c070: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
c080: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
c090: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
c0a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c0b0: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
c0c0: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
c0d0: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
c0e0: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
c0f0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
c100: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
c110: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
c120: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
c130: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
c140: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
c150: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
c160: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
c170: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
c180: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
c190: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c1a0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
c1b0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
c1c0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
c1d0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
c1e0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
c1f0: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
c200: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
c210: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
c220: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
c230: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
c240: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
c250: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
c260: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
c270: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
c280: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
c290: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
c2a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c2b0: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
c2c0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
c2d0: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
c2e0: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
c2f0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
c300: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c310: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
c320: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
c330: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
c340: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
c350: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c360: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
c370: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
c380: 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
c390: 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
c3a0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c3b0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
c3c0: 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
c3d0: 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
c3e0: 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
c3f0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
c400: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
c410: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
c420: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
c430: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
c440: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
c450: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
c460: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
c470: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
c480: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
c490: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
c4a0: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
c4b0: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
c4c0: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
c4d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c4e0: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
c4f0: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
c500: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
c510: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
c520: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
c530: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
c540: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c550: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
c560: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
c570: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c580: 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
c590: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
c5a0: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
c5b0: 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
c5c0: 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
c5d0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
c5e0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
c5f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
c600: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
c610: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
c620: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
c630: 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
c640: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
c650: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
c660: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
c670: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
c680: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
c690: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
c6a0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
c6b0: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
c6c0: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
c6d0: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
c6e0: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
c6f0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
c700: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
c710: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
c720: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
c730: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
c740: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
c750: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
c760: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
c770: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
c780: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
c790: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
c7a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
c7b0: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
c7c0: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
c7d0: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
c7e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c7f0: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
c800: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
c810: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
c820: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
c830: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
c840: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
c850: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
c860: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
c870: 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
c880: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
c890: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
c8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
c8b0: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
c8c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
c8d0: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
c8e0: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
c8f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c900: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
c910: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
c920: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
c930: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c940: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
c950: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
c960: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
c970: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
c980: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
c990: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
c9a0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
c9b0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
c9c0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
c9d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
c9e0: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
c9f0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ca00: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ca10: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
ca20: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
ca30: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
ca40: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
ca50: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
ca60: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
ca70: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
ca80: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
ca90: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
caa0: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
cab0: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
cac0: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
cad0: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
cae0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
caf0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
cb00: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
cb10: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
cb20: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
cb30: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
cb40: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
cb50: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
cb60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
cb70: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
cb80: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
cb90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cba0: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
cbb0: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
cbc0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
cbd0: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
cbe0: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
cbf0: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
cc00: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
cc10: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
cc20: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
cc30: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
cc40: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
cc50: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
cc60: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
cc70: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
cc80: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
cc90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
ccb0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
ccc0: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
ccd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
cce0: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
ccf0: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
cd00: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
cd10: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
cd20: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
cd30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cd40: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
cd50: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
cd60: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
cd70: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
cd80: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
cd90: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
cda0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
cdb0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
cdc0: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
cdd0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
cde0: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
cdf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ce00: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
ce10: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
ce20: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
ce30: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
ce40: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
ce50: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
ce60: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
ce70: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
ce80: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
ce90: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
cea0: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
ceb0: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
cec0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
ced0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
cee0: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
cef0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
cf00: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
cf10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
cf20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
cf30: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
cf40: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
cf50: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
cf60: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
cf70: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
cf80: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
cf90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
cfa0: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
cfb0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
cfc0: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
cfd0: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
cfe0: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
cff0: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
d000: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
d010: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
d020: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
d030: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
d040: 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
d050: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
d060: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
d070: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
d080: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
d090: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
d0a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d0b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
d0c0: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
d0d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
d0e0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
d0f0: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
d100: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
d110: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
d120: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
d130: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
d140: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
d150: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
d160: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
d170: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
d180: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
d190: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
d1a0: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
d1b0: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
d1c0: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
d1d0: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
d1e0: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
d1f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d200: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
d210: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
d220: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
d230: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
d240: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
d250: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
d260: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
d270: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
d280: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
d290: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
d2a0: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
d2b0: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
d2c0: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
d2d0: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
d2e0: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
d2f0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
d300: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
d310: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
d320: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
d330: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
d340: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
d350: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d360: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
d370: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
d380: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
d390: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
d3a0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
d3b0: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
d3c0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
d3d0: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
d3e0: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
d3f0: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
d400: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
d410: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
d420: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
d430: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
d440: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
d450: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
d460: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
d470: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
d480: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
d490: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
d4a0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
d4b0: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
d4c0: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
d4d0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
d4e0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
d4f0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
d500: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
d510: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
d520: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
d530: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
d540: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
d550: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
d560: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d570: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
d580: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
d590: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
d5a0: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
d5b0: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
d5c0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
d5d0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
d5e0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
d5f0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
d600: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
d610: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
d620: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
d630: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
d640: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
d650: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d660: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
d670: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
d680: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
d690: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
d6a0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
d6b0: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
d6c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d6d0: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
d6e0: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
d6f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
d700: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
d710: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
d720: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
d730: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
d740: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
d750: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
d760: 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
d770: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
d780: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
d790: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
d7a0: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
d7b0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
d7c0: 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
d7d0: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
d7e0: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
d7f0: 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
d800: 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
d810: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
d820: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
d830: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
d840: 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
d850: 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
d860: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d870: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
d880: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
d890: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
d8a0: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
d8b0: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
d8c0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
d8d0: 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
d8e0: 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
d8f0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
d900: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
d910: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
d920: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d930: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
d940: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
d950: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d960: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
d970: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
d980: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
d990: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
d9a0: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
d9b0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
d9c0: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
d9d0: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
d9e0: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
d9f0: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
da00: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
da10: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
da20: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
da30: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
da40: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
da50: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
da60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
da70: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
da80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
da90: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
daa0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
dab0: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
dac0: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
dad0: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
dae0: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
daf0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
db00: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
db10: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
db20: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
db30: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
db40: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
db50: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
db60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
db70: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
db80: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
db90: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
dba0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
dbb0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
dbc0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
dbd0: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
dbe0: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
dbf0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
dc00: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
dc10: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
dc20: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
dc30: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
dc40: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
dc50: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
dc60: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
dc70: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
dc80: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
dc90: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
dca0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
dcb0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
dcc0: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
dcd0: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
dce0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
dcf0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
dd00: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
dd10: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
dd20: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
dd30: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
dd40: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
dd50: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
dd60: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
dd70: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
dd80: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
dd90: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
dda0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
ddb0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
ddc0: 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
ddd0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
dde0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
ddf0: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
de00: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
de10: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
de20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
de30: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
de40: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
de50: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
de60: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
de70: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
de80: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
de90: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
dea0: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
deb0: 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
dec0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
ded0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
dee0: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
def0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
df00: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
df10: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
df20: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
df30: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
df40: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
df50: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
df60: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
df70: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
df80: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
df90: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
dfa0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
dfb0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
dfc0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
dfd0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dfe0: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
dff0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
e000: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
e010: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
e020: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
e030: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
e040: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
e050: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
e060: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
e070: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
e080: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
e090: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
e0a0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
e0b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e0c0: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
e0d0: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
e0e0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
e0f0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
e100: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
e110: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
e120: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
e130: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
e140: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
e150: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
e160: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
e170: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
e180: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
e190: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
e1a0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
e1b0: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
e1c0: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
e1d0: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
e1e0: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
e1f0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
e200: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
e210: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
e220: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
e230: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
e240: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
e250: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
e260: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
e270: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
e280: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
e290: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
e2a0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
e2b0: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
e2c0: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
e2d0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
e2e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
e2f0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
e300: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
e310: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
e320: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
e330: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
e340: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
e350: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
e360: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
e370: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
e380: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
e390: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
e3a0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
e3b0: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
e3c0: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
e3d0: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
e3e0: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
e3f0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
e400: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
e410: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
e420: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
e430: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
e440: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
e450: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
e460: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
e470: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
e480: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
e490: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
e4a0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
e4b0: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
e4c0: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
e4d0: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
e4e0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
e4f0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
e500: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
e510: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
e520: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
e530: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
e540: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
e550: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
e560: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
e570: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
e580: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
e590: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
e5a0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
e5b0: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
e5c0: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
e5d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e5e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
e5f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
e600: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e610: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
e620: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
e630: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
e640: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
e650: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
e660: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
e670: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
e680: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
e690: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
e6a0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
e6b0: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
e6c0: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
e6d0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
e6e0: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
e6f0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
e700: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
e710: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
e720: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
e730: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
e740: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
e750: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
e760: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
e770: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
e780: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
e790: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
e7a0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
e7b0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
e7c0: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
e7d0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
e7e0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
e7f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e800: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
e810: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
e820: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
e830: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
e840: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
e850: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e860: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
e870: 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
e880: 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
e890: 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
e8a0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
e8b0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
e8c0: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
e8d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e8e0: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
e8f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
e900: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e910: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
e920: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
e930: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
e940: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e950: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
e960: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
e970: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
e980: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
e990: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
e9a0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
e9b0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
e9c0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
e9d0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
e9e0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
e9f0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
ea00: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
ea10: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
ea20: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
ea30: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ea40: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
ea50: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
ea60: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
ea70: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
ea80: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
ea90: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
eaa0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
eab0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
eac0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
ead0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
eae0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
eaf0: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
eb00: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
eb10: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
eb20: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
eb30: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
eb40: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
eb50: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
eb60: 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
eb70: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
eb80: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
eb90: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
eba0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
ebb0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
ebc0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
ebd0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
ebe0: 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
ebf0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ec00: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ec10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ec20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
ec30: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
ec40: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
ec50: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
ec60: 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
ec70: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
ec80: 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
ec90: 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
eca0: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
ecb0: 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
ecc0: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
ecd0: 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
ece0: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
ecf0: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
ed00: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ed10: 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
ed20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
ed30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
ed40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
ed50: 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
ed60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
ed70: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
ed80: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
ed90: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
eda0: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
edb0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
edc0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
edd0: 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
ede0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
edf0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ee00: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
ee10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ee20: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
ee30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
ee40: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
ee50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
ee60: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
ee70: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
ee80: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
ee90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
eea0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
eeb0: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
eec0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
eed0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
eee0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
eef0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
ef00: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
ef10: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
ef20: 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
ef30: 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
ef40: 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
ef50: 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
ef60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
ef70: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
ef80: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
ef90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
efa0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
efb0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
efc0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
efd0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
efe0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
eff0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
f000: 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
f010: 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
f020: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
f030: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
f040: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
f050: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
f060: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
f070: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
f080: 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
f090: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
f0a0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
f0b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
f0c0: 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
f0d0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f0e0: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
f0f0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
f100: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f110: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
f120: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
f130: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
f140: 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
f150: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
f160: 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
f170: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
f180: 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
f190: 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
f1a0: 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
f1b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f1c0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
f1d0: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
f1e0: 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
f1f0: 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
f200: 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
f210: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f220: 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
f230: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
f240: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f250: 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
f260: 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
f270: 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
f280: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
f290: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
f2a0: 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
f2b0: 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
f2c0: 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
f2d0: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
f2e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f2f0: 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
f300: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
f310: 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
f320: 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
f330: 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
f340: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f350: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
f360: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
f370: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
f380: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
f390: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
f3a0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
f3b0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
f3c0: 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
f3d0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
f3e0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
f3f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
f400: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
f410: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
f420: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
f430: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f440: 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
f450: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
f460: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f470: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
f480: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f490: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
f4a0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f4b0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f4c0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f4d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f4e0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
f4f0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f500: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
f510: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
f520: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
f530: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
f540: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
f550: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f560: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
f570: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
f580: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f590: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
f5a0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
f5b0: 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
f5c0: 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
f5d0: 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
f5e0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
f5f0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f600: 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
f610: 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
f620: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
f630: 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
f640: 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
f650: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
f660: 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
f670: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
f680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f690: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f6a0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f6b0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f6d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f6e0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
f6f0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f700: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
f710: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
f720: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
f730: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
f740: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
f750: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
f760: 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
f770: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
f780: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
f790: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
f7a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
f7b0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
f7c0: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
f7d0: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
f7e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
f7f0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
f800: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
f810: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
f820: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
f830: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
f840: 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
f850: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f860: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
f870: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f880: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
f890: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
f8a0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
f8b0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
f8c0: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
f8d0: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
f8e0: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
f8f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
f900: 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
f910: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
f920: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
f930: 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
f940: 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
f950: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f960: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
f970: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
f980: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
f990: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
f9a0: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
f9b0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
f9c0: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
f9d0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
f9e0: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
f9f0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fa00: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
fa10: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
fa20: 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
fa30: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
fa40: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
fa50: 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
fa60: 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
fa70: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
fa80: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
fa90: 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
faa0: 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
fab0: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
fac0: 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
fad0: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
fae0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
faf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
fb00: 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
fb10: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
fb20: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
fb30: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
fb40: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
fb50: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
fb60: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
fb70: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
fb80: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
fb90: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
fba0: 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
fbb0: 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
fbc0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
fbd0: 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
fbe0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
fbf0: 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
fc00: 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
fc10: 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
fc20: 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
fc30: 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
fc40: 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
fc50: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
fc60: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
fc70: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
fc80: 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
fc90: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
fca0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
fcb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
fcc0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
fcd0: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
fce0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
fcf0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
fd00: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
fd10: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
fd20: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
fd30: 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
fd40: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
fd50: 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
fd60: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
fd70: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
fd80: 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
fd90: 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
fda0: 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
fdb0: 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
fdc0: 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
fdd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
fde0: 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
fdf0: 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
fe00: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
fe10: 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
fe20: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
fe30: 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
fe40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fe50: 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
fe60: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
fe70: 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
fe80: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
fe90: 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
fea0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
feb0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
fec0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fed0: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
fee0: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
fef0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
ff00: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
ff10: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
ff20: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
ff30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
ff40: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
ff50: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
ff60: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
ff70: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
ff80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
ff90: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
ffa0: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
ffb0: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
ffc0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
ffd0: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
ffe0: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
fff0: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f  _CONFIG_PCACHE o
10000 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
10010 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
10020 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
10030 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
10040 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
10050 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
10060 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
10070 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
10080 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
10090 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
100a0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
100b0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
100c0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
100d0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
100e0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
100f0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
10100 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
10110 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
10120 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
10130 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
10140 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
10150 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
10160 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
10170 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
10180 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
10190 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
101a0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
101b0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
101c0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
101d0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
101e0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
101f0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
10200 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
10210 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
10220 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
10230 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
10240 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
10250 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
10260 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10270 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
10280 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
10290 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
102a0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
102b0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
102c0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
102d0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
102e0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
102f0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10300 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
10310 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
10320 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
10330 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
10340 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
10350 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
10360 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
10370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10380 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
10390 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
103a0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
103b0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
103c0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
103d0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
103e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
103f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
10400 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10410 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
10420 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10430 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
10440 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
10450 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
10460 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
10470 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
10480 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
10490 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
104a0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
104b0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
104c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
104d0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
104e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
104f0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
10500 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
10510 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
10520 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
10530 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
10540 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10550 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
10560 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
10570 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10580 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
10590 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
105a0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
105b0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
105c0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
105d0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
105e0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
105f0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
10600 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
10610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
10620 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
10630 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
10640 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
10650 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
10660 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
10670 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
10680 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
10690 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
106a0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
106b0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
106c0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
106d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
106e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
106f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
10700 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
10710 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
10720 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10730 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
10740 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10750 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10760 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
10770 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
10780 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
10790 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
107a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
107b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
107c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
107d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
107e0 63 61 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20  capped at 2^12. 
107f0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
10800 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
10810 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10820 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72  size are 2^5 thr
10830 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a  ough 2^8.</dd>.*
10840 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10850 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
10860 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
10870 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
10880 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10890 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
108a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
108b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
108c0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
108d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
108e0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
108f0 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
10900 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
10910 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
10920 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
10930 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
10940 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
10950 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
10960 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
10970 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
10980 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10990 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
109a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
109b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
109c0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
109d0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
109e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
109f0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
10a00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10a10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10a20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10a30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10a40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10a50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10a60 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
10a70 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10a80 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10a90 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10aa0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10ab0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ac0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
10ad0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
10ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10af0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
10b00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10b10 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
10b20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
10b30 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
10b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10b50 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
10b60 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10b70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10b80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10b90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10ba0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
10bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
10bc0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
10bd0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
10be0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10bf0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
10c00 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
10c10 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
10c20 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
10c30 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
10c40 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
10c50 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
10c60 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
10c70 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
10c80 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
10c90 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
10ca0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
10cb0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
10cc0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
10cd0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
10ce0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
10cf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10d00 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
10d10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10d20 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
10d30 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
10d40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10d50 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
10d60 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
10d70 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10d80 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10d90 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
10da0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10db0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
10dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10dd0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
10de0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
10df0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
10e00 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
10e10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10e20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
10e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10e40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
10e50 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
10e60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
10e70 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
10e80 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
10e90 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
10ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
10eb0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
10ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
10ed0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
10ee0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10ef0 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
10f00 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10f10 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10f20 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10f30 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
10f40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
10f50 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
10f60 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
10f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10f80 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
10f90 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
10fa0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
10fb0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
10fc0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
10fd0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
10fe0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
10ff0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
11000 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
11010 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
11020 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
11030 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
11040 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
11050 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
11070 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
11080 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
11090 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
110a0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
110b0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
110c0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
110d0 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
110e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
110f0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
11100 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
11110 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
11120 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
11130 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
11140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
11150 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
11160 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
11170 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
11180 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
11190 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
111a0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
111b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
111c0 5f 47 45 54 50 43 41 43 48 45 5d 5d 20 3c 64 74  _GETPCACHE]] <dt
111d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
111e0 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  ETPCACHE</dt>.**
111f0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11200 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11210 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11220 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11230 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
11240 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
11250 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
11260 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
11270 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
11280 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
11290 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
112a0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
112b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
112c0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
112d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
112e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
112f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11300 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
11310 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
11320 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
11330 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
11340 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
11350 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
11360 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
11370 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
11380 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
11390 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
113a0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
113b0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
113c0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
113d0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
113e0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
113f0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
11400 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
11410 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
11420 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
11430 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
11440 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
11450 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
11460 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
11470 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11480 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
11490 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
114a0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
114b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
114c0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
114d0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
114e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
114f0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
11500 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
11510 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
11520 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
11530 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
11540 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
11550 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11560 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
11570 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
11580 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
11590 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
115a0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
115b0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
115c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
115d0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
115e0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
115f0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
11600 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
11610 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
11620 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
11630 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
11640 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
11650 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
11660 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
11670 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
11680 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
11690 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
116a0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
116b0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
116c0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
116d0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
116e0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
116f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
11700 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
11710 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
11720 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
11730 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11740 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
11750 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11760 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
11770 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11780 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11790 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
117a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
117b0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
117c0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
117d0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
117e0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
117f0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
11800 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
11810 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
11820 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
11830 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
11840 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
11850 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
11860 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
11870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
11880 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
11890 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
118a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
118b0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
118c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
118d0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
118e0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
118f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
11900 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
11910 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
11920 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
11930 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
11940 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
11950 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
11960 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
11970 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
11980 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
11990 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
119a0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
119b0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
119c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
119d0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
119e0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
119f0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
11a00 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
11a10 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
11a20 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
11a30 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
11a40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
11a50 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
11a60 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  fined..** </dl>.
11a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11a80 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11a90 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
11aa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11ab0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11ac0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
11ad0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
11ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11af0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
11b00 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
11b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11b20 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
11b30 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11b40 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
11b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11b60 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
11b70 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
11b80 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11b90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11ba0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
11bb0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
11bc0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
11bd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11be0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
11bf0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
11c00 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
11c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11c20 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
11c30 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
11c40 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
11c50 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
11c60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11c70 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
11c80 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
11c90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11ca0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
11cb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
11cc0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
11cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11ce0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
11cf0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
11d00 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
11d10 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
11d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
11d30 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
11d40 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
11d50 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
11d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
11d70 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
11d80 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
11d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11da0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
11db0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
11dc0 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
11dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11de0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
11df0 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
11e00 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
11e10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11e20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
11e30 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
11e40 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
11e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11e60 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
11e70 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a   17  /* int */..
11e80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11e90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
11ea0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
11eb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
11ec0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
11ed0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11ee0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11ef0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11f00 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11f10 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
11f20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
11f40 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11f50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11f60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11f70 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
11f80 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
11f90 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
11fa0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
11fb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11fc0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
11fd0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11fe0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11ff0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
12000 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
12010 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12020 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12030 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12040 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
12050 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12060 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
12070 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
12080 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12090 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
120a0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
120b0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
120c0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
120d0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
120e0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
120f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
12100 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
12110 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12120 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
12130 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
12140 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
12150 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
12160 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
12170 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
12180 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
12190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
121a0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
121b0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
121c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
121d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
121e0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
121f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
12200 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
12210 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
12220 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
12230 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
12240 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
12250 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12260 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
12270 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
12280 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
12290 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
122a0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
122b0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
122c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
122d0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
122e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
122f0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
12300 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
12310 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
12320 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
12330 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
12340 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
12350 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
12360 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12370 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
12380 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
12390 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
123a0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
123b0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
123c0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
123d0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
123e0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
123f0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
12400 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12410 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
12420 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12430 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
12440 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
12450 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
12460 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
12470 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
12480 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
12490 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
124a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
124b0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
124c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
124d0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
124e0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
124f0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
12500 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
12510 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
12520 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
12530 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
12540 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
12550 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
12560 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
12570 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
12580 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
12590 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
125a0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
125b0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
125c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
125d0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
125e0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
125f0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
12600 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
12610 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
12620 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
12630 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
12640 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
12650 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
12660 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
12670 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
12680 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
12690 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
126a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
126b0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
126c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
126d0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
126e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
126f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
12700 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
12710 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
12720 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
12730 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
12740 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
12750 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
12760 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
12770 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
12780 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
12790 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
127a0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
127b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
127c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
127d0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
127e0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
127f0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
12800 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
12810 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
12820 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
12830 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
12840 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12850 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
12860 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
12870 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
12880 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
12890 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
128a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
128b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
128c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
128d0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
128e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
128f0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
12900 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
12910 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
12920 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
12930 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
12940 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
12950 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
12960 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12970 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
12980 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
12990 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
129a0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
129b0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
129c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
129d0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
129e0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
129f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12a00 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
12a10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
12a20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
12a30 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
12a40 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
12a50 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
12a60 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
12a70 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
12a80 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
12a90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12aa0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
12ab0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
12ac0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
12ad0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
12ae0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
12af0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
12b00 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
12b10 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
12b20 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
12b30 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
12b40 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12b50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
12b60 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
12b70 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
12b80 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
12b90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
12ba0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
12bb0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
12bc0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
12bd0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
12be0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
12bf0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
12c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
12c10 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
12c20 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
12c30 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
12c40 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
12c50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12c60 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
12c70 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
12c80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
12c90 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
12ca0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
12cb0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
12cc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
12cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
12ce0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
12cf0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
12d00 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
12d10 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
12d20 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
12d30 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
12d40 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
12d50 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
12d60 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
12d70 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
12d80 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
12d90 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
12da0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
12db0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
12dc0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
12dd0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
12de0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
12df0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
12e00 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
12e10 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
12e20 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
12e30 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
12e40 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
12e50 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
12e60 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
12e70 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
12e80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
12e90 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
12ea0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
12eb0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
12ec0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
12ed0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
12ee0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
12ef0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
12f00 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
12f10 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
12f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
12f30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12f40 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
12f50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
12f60 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
12f70 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
12f80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
12f90 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
12fa0 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
12fb0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
12fc0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
12fd0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
12fe0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
12ff0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
13000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13010 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
13020 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
13030 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
13040 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
13050 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
13060 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
13070 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
13080 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
13090 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
130a0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
130b0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
130c0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
130d0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
130e0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
130f0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
13100 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
13110 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
13120 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
13130 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13140 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
13150 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
13160 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
13170 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
13180 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
13190 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
131a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
131b0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
131c0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
131d0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
131e0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
131f0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
13200 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
13210 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
13220 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
13230 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
13240 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
13250 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
13260 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
13270 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
13280 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
13290 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
132a0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
132b0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
132c0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
132d0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
132e0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
132f0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
13300 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
13310 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
13320 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
13330 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
13340 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
13350 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
13360 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
13370 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
13380 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
13390 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
133a0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
133b0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
133c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
133d0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
133e0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
133f0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
13400 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
13410 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
13420 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
13430 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
13440 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
13450 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
13460 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
13470 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
13480 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
13490 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
134a0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
134b0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
134c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
134d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
134e0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
134f0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
13500 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
13510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
13520 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
13530 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
13540 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
13550 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
13560 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
13570 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
13580 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
13590 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
135a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
135b0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
135c0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
135d0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
135e0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
135f0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
13600 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
13610 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
13620 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
13630 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
13640 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
13650 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13660 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
13670 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
13680 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
13690 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
136a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
136b0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
136c0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
136d0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
136e0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
136f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
13700 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
13710 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
13720 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13730 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
13740 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
13750 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
13760 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
13770 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
13780 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
13790 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
137a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
137b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
137c0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
137d0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
137e0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
137f0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
13800 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
13810 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
13820 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
13830 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
13840 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
13850 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
13860 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
13870 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
13880 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
13890 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
138a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
138b0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
138c0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
138d0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
138e0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
138f0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
13900 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
13910 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
13920 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
13930 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
13940 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
13950 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
13960 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
13970 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
13980 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
13990 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
139a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
139b0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
139c0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
139d0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
139e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
139f0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
13a00 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
13a10 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
13a20 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
13a30 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
13a40 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
13a50 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
13a60 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
13a70 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
13a80 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
13a90 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
13aa0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
13ab0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
13ac0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
13ad0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
13ae0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
13af0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
13b00 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
13b10 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
13b20 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
13b30 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
13b40 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
13b50 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
13b60 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
13b70 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
13b80 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
13b90 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
13ba0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
13bb0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
13bc0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
13bd0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
13be0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
13bf0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
13c00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
13c10 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
13c20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
13c30 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
13c40 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
13c50 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
13c60 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
13c70 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13c80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13c90 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
13ca0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
13cb0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
13cc0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
13cd0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
13ce0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
13cf0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
13d00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
13d10 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
13d20 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
13d30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
13d40 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
13d50 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
13d60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
13d70 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
13d80 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
13d90 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
13da0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
13db0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
13dc0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
13dd0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
13de0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
13df0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
13e00 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
13e10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
13e20 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
13e30 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
13e40 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
13e50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
13e60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
13e70 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
13e80 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
13e90 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
13ea0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
13eb0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
13ec0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
13ed0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
13ee0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
13ef0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
13f00 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
13f10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
13f20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
13f30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
13f40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
13f50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
13f60 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
13f70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
13f80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
13f90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
13fa0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
13fb0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
13fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
13fd0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
13fe0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
13ff0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
14000 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
14010 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
14020 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
14030 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
14040 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
14050 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
14060 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
14070 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
14080 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
14090 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
140a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
140b0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
140c0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
140d0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
140e0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
140f0 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
14100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14110 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
14120 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
14130 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
14140 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
14150 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
14160 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
14170 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
14180 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
14190 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
141a0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
141b0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
141c0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
141d0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
141e0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
141f0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
14200 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
14210 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
14220 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
14230 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
14240 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
14250 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
14260 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
14270 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
14280 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
14290 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
142a0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
142b0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
142c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
142d0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
142e0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
142f0 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
14300 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
14310 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
14320 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
14330 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
14340 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
14350 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
14360 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
14370 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
14380 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
14390 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
143a0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
143b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
143c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
143d0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
143e0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
143f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
14400 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
14410 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
14420 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
14430 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
14440 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14450 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
14460 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
14470 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
14480 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
14490 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
144a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
144b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
144c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
144d0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
144e0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
144f0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
14500 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
14510 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
14520 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
14530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14540 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
14550 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
14560 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14570 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
14580 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
14590 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
145a0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
145b0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
145c0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
145d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
145e0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
145f0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
14600 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
14610 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
14620 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
14630 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
14640 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
14650 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
14660 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
14670 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
14680 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
14690 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
146a0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
146b0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
146c0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
146d0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
146e0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
146f0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
14700 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
14710 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
14720 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
14730 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
14740 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
14750 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
14760 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
14770 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14780 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
14790 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
147a0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
147b0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
147c0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
147d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
147e0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
147f0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
14800 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
14810 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
14820 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
14830 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
14840 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
14850 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
14860 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
14870 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
14880 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14890 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
148a0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
148b0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
148c0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
148d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
148e0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
148f0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
14900 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
14910 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
14920 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
14930 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
14940 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
14950 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14960 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
14970 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
14980 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
14990 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
149a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
149b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
149c0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
149d0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
149e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
149f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
14a00 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
14a10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
14a20 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
14a30 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
14a40 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
14a50 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
14a60 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
14a70 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
14a80 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
14a90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14aa0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
14ab0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
14ac0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
14ad0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
14ae0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
14af0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
14b00 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
14b10 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
14b20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14b30 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
14b40 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
14b50 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
14b60 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
14b70 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
14b80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14b90 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
14ba0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
14bb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
14bc0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
14bd0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
14be0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
14bf0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
14c00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
14c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14c20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
14c30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14c40 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
14c50 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
14c60 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
14c70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
14c80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
14c90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
14ca0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
14cb0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
14cc0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
14cd0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
14ce0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
14cf0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
14d00 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
14d10 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
14d20 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
14d30 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
14d40 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
14d50 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
14d60 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
14d70 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
14d80 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
14d90 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
14da0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
14db0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
14dc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
14dd0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
14de0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
14df0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
14e00 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
14e10 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
14e20 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
14e30 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
14e40 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
14e50 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
14e60 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
14e70 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
14e80 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
14e90 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
14ea0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
14eb0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
14ec0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
14ed0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
14ee0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
14ef0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
14f00 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
14f10 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
14f20 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
14f30 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
14f40 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
14f50 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
14f60 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
14f70 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
14f80 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
14f90 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
14fa0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
14fb0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
14fc0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
14fd0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
14fe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
14ff0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
15000 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
15010 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
15020 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15030 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
15040 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
15050 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
15060 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
15070 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
15080 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
15090 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
150a0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
150b0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
150c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
150d0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
150e0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
150f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
15100 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
15110 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
15120 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15130 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
15140 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
15150 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
15160 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
15170 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15180 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
15190 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
151a0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
151b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
151c0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
151d0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
151e0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
151f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
15200 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
15210 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
15220 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
15230 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
15240 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
15250 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
15260 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
15270 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
15280 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
15290 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
152a0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
152b0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
152c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
152d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
152e0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
152f0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
15300 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
15310 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15320 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
15330 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
15340 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
15350 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
15360 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
15370 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
15380 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
15390 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
153a0 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
153b0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
153c0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
153d0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
153e0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
153f0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
15400 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
15410 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
15420 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
15430 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
15440 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
15450 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
15460 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15470 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
15480 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
15490 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
154a0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
154b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
154c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
154d0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
154e0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
154f0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
15500 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
15510 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15520 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
15530 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
15540 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
15550 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
15560 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
15570 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
15580 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
15590 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
155a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
155b0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
155c0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
155d0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
155e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
155f0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
15600 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
15610 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
15620 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
15630 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15640 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
15650 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
15660 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
15670 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
15680 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
15690 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
156a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
156b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
156c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
156d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
156e0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
156f0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
15700 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
15710 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
15720 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
15730 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
15740 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
15750 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
15760 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
15770 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
15780 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
15790 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
157a0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
157b0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
157c0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
157d0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
157e0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
157f0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
15800 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
15810 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
15820 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
15830 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
15840 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
15850 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
15860 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
15870 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
15880 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
15890 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
158a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
158b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
158c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
158d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
158e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
158f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
15900 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
15910 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
15920 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
15930 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
15940 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
15950 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
15960 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
15970 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
15980 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
15990 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
159a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
159b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
159c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
159d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
159e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
159f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
15a00 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
15a10 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
15a20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
15a30 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
15a40 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
15a50 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
15a60 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
15a70 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
15a80 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
15a90 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
15aa0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
15ab0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
15ac0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
15ad0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
15ae0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
15af0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
15b00 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
15b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
15b20 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
15b30 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
15b40 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
15b50 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
15b60 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
15b70 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
15b80 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
15b90 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
15ba0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
15bb0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
15bc0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
15bd0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
15be0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
15bf0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
15c00 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
15c10 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
15c20 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
15c30 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
15c40 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
15c50 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
15c60 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
15c70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
15c80 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
15c90 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
15ca0 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
15cb0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
15cc0 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
15cd0 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
15ce0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
15cf0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
15d00 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
15d10 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
15d20 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
15d30 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
15d40 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
15d50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
15d60 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
15d70 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
15d80 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
15d90 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
15da0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
15db0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
15dc0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
15dd0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
15de0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
15df0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
15e00 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
15e10 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
15e20 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
15e30 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
15e40 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
15e50 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
15e60 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
15e70 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
15e80 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
15e90 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
15ea0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
15eb0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
15ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15ed0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
15ee0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
15ef0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
15f00 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
15f10 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
15f20 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
15f30 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
15f40 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
15f50 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
15f60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
15f70 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
15f80 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
15f90 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
15fa0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
15fb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
15fc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
15fd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
15fe0 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
15ff0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
16000 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
16010 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
16020 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
16030 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
16040 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
16050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
16060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
16070 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
16080 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
16090 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
160a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
160b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
160c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
160d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
160e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
160f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
16100 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
16110 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
16120 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
16130 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
16140 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
16150 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
16160 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
16170 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
16180 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
16190 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
161a0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
161b0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
161c0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
161d0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
161e0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
161f0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
16200 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
16210 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
16220 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
16230 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
16240 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
16250 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
16260 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
16270 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
16280 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
16290 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
162a0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
162b0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
162c0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
162d0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
162e0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
162f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
16300 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
16310 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
16320 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
16330 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
16340 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
16350 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
16360 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
16370 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
16380 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
16390 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
163a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
163b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
163c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
163d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
163e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
163f0 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
16400 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
16410 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
16420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16430 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
16440 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
16450 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
16460 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
16470 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
16480 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
16490 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
164a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
164b0 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
164c0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
164d0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
164e0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
164f0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
16500 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
16510 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
16520 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
16530 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16540 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
16550 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
16560 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
16570 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
16580 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
16590 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
165a0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
165b0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
165c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
165d0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
165e0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
165f0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
16600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
16610 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
16620 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
16630 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
16640 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
16650 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
16660 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
16670 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
16680 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
16690 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
166a0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
166b0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
166c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
166d0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
166e0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
166f0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
16700 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
16710 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
16720 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
16730 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
16740 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
16750 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
16760 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
16770 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
16780 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
16790 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
167a0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
167b0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
167c0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
167d0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
167e0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
167f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
16800 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
16810 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
16820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16830 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
16840 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
16850 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
16860 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
16870 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
16880 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
16890 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
168a0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
168b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
168c0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
168d0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
168e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
168f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
16900 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
16910 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
16920 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
16930 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
16940 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
16950 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
16960 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
16970 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16980 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
16990 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
169a0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
169b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
169c0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
169d0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
169e0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
169f0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
16a00 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
16a10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16a20 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
16a30 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
16a40 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
16a50 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
16a60 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
16a70 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
16a80 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
16a90 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16aa0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
16ab0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
16ac0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
16ad0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
16ae0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
16af0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
16b00 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
16b10 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
16b20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
16b30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
16b40 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
16b50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16b60 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
16b70 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16b80 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
16b90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16ba0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
16bb0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
16bc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
16bd0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
16be0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
16bf0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
16c00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
16c10 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
16c20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16c30 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
16c40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
16c50 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
16c60 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
16c70 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
16c80 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
16c90 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
16ca0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
16cb0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
16cc0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
16cd0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
16ce0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
16cf0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
16d00 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
16d10 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
16d20 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
16d30 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
16d40 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
16d50 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
16d60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16d70 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
16d80 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
16d90 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
16da0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
16db0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
16dc0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
16dd0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
16de0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
16df0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
16e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
16e10 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
16e20 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
16e30 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
16e40 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
16e50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
16e60 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
16e70 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
16e80 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
16e90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
16ea0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
16eb0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
16ec0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
16ed0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
16ee0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
16ef0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
16f00 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
16f10 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
16f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
16f30 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
16f40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
16f50 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
16f60 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
16f70 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
16f80 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
16f90 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
16fa0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
16fb0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
16fc0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
16fd0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
16fe0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
16ff0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
17000 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
17010 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
17020 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
17030 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
17040 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
17050 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
17060 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
17070 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
17080 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17090 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
170a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
170b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
170c0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
170d0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
170e0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
170f0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
17100 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
17110 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
17120 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
17130 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
17140 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
17150 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
17160 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
17170 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
17180 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
17190 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
171a0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
171b0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
171c0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
171d0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
171e0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
171f0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
17200 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
17210 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
17220 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
17230 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
17240 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
17250 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
17260 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17270 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
17280 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
17290 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
172a0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
172b0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
172c0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
172d0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
172e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
172f0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
17300 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
17310 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
17320 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
17330 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
17340 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
17350 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
17360 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
17370 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
17380 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
17390 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
173a0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
173b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
173c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
173d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
173e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
173f0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
17400 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
17410 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
17420 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
17430 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
17440 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
17450 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
17460 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
17470 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
17480 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
17490 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
174a0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
174b0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
174c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
174d0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
174e0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
174f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
17500 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
17510 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
17520 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
17530 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
17540 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
17550 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
17560 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
17570 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
17580 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
17590 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
175a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
175b0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
175c0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
175d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
175e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
175f0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
17600 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
17610 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
17620 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
17630 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
17640 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
17650 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
17660 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
17670 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
17680 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
17690 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
176a0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
176b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
176c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
176d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
176e0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
176f0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
17700 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
17710 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
17720 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
17730 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
17740 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
17750 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
17760 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
17770 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
17780 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
17790 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
177a0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
177b0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
177c0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
177d0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
177e0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
177f0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
17800 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
17810 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
17820 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
17830 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
17840 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
17850 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
17860 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
17870 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
17880 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
17890 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
178a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
178b0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
178c0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
178d0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
178e0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
178f0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
17900 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
17910 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
17920 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
17930 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
17940 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
17950 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
17960 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
17970 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
17980 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
17990 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
179a0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
179b0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
179c0 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
179d0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
179e0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
179f0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
17a00 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
17a10 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
17a20 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
17a30 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
17a40 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
17a50 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
17a60 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
17a70 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
17a80 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
17a90 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
17aa0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
17ab0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
17ac0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
17ad0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
17ae0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
17af0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
17b00 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
17b10 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
17b20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17b30 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
17b40 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
17b50 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
17b60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
17b70 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
17b80 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
17b90 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
17ba0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
17bb0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
17bc0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
17bd0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
17be0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
17bf0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
17c00 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
17c10 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
17c20 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
17c30 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
17c40 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
17c50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17c60 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
17c70 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
17c80 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
17c90 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
17ca0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
17cb0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
17cc0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
17cd0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
17ce0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
17cf0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
17d00 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
17d10 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
17d20 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
17d30 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
17d40 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
17d50 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
17d60 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
17d70 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
17d80 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
17d90 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
17da0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
17db0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17dc0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17dd0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
17de0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
17df0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17e00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
17e10 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
17e20 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
17e30 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
17e40 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
17e50 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
17e60 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
17e70 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
17e80 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
17e90 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
17ea0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
17eb0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
17ec0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
17ed0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
17ee0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
17ef0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
17f00 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
17f10 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
17f20 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
17f30 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
17f40 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
17f50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
17f60 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
17f70 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
17f80 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
17f90 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
17fa0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
17fb0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
17fc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
17fd0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
17fe0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
17ff0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
18000 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
18010 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
18020 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
18030 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
18040 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
18050 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
18060 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18070 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
18080 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
18090 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
180a0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
180b0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
180c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
180d0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
180e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
180f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
18100 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
18110 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
18120 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
18130 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
18140 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
18150 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
18160 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
18170 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
18180 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
18190 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
181a0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
181b0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
181c0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
181d0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
181e0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
181f0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
18200 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
18210 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
18220 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
18230 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
18240 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
18250 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
18260 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
18270 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
18280 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
18290 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
182a0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
182b0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
182c0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
182d0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
182e0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
182f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
18300 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
18310 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
18320 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
18330 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
18340 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
18350 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
18360 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
18370 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
18380 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
18390 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
183a0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
183b0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
183c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
183d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
183e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
183f0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
18400 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
18410 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
18420 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
18430 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
18440 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18450 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
18460 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
18470 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
18480 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
18490 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
184a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
184b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
184c0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
184d0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
184e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
184f0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
18500 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
18510 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
18520 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
18530 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
18540 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
18550 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
18560 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
18570 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
18580 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
18590 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
185a0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
185b0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
185c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
185d0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
185e0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
185f0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
18600 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
18610 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
18620 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
18630 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
18640 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
18650 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
18660 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
18670 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
18680 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
18690 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
186a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
186b0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
186c0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
186d0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
186e0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
186f0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
18700 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
18710 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
18720 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
18730 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18740 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
18750 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
18760 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
18770 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
18780 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18790 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
187a0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
187b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
187c0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
187d0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
187e0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
187f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
18800 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
18810 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
18820 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
18830 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
18840 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18850 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
18860 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
18870 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
18880 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
18890 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
188a0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
188b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
188c0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
188d0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
188e0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
188f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
18900 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
18910 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
18920 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
18930 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
18940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18950 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18960 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
18970 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
18980 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
18990 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
189a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
189b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
189c0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
189d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
189e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
189f0 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
18a00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
18a10 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
18a20 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
18a30 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
18a40 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
18a50 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
18a60 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
18a70 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
18a80 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
18a90 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
18aa0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
18ab0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
18ac0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
18ad0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
18ae0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
18af0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
18b00 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
18b10 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
18b20 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
18b30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
18b40 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
18b50 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
18b60 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
18b70 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
18b80 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
18b90 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
18ba0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
18bb0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18bc0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
18bd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18be0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
18bf0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
18c00 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
18c10 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
18c20 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
18c30 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
18c40 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
18c50 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
18c60 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
18c70 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
18c80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
18c90 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
18ca0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
18cb0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
18cc0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
18cd0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
18ce0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
18cf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
18d00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18d10 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
18d20 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
18d30 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
18d40 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
18d50 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
18d60 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
18d70 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
18d80 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
18d90 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
18da0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
18db0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
18dc0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
18dd0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
18de0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
18df0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
18e00 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
18e10 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
18e20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
18e30 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
18e40 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
18e50 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
18e60 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
18e70 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
18e80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
18e90 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
18ea0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
18eb0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
18ec0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
18ed0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
18ee0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
18ef0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
18f00 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
18f10 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
18f20 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
18f30 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
18f40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
18f50 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
18f60 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
18f70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
18f80 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
18f90 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
18fa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18fb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
18fc0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
18fd0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
18fe0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
18ff0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
19000 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
19010 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
19020 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
19030 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
19040 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
19050 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
19060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19070 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
19080 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
19090 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
190a0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
190b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
190c0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
190d0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
190e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
190f0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
19100 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
19110 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
19120 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
19130 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
19140 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
19150 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
19160 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
19170 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
19180 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
19190 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
191a0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
191b0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
191c0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
191d0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
191e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
191f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19200 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
19210 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
19220 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
19230 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
19240 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
19250 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
19260 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
19270 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19280 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
19290 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
192a0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
192b0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
192c0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
192d0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
192e0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
192f0 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
19300 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
19310 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
19320 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
19330 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
19340 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
19350 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
19360 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
19370 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
19380 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
19390 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
193a0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
193b0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
193c0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
193d0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
193e0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
193f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
19400 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
19410 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
19420 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
19430 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
19440 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
19450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
19460 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
19470 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
19480 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
19490 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
194a0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
194b0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
194c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
194d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
194e0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
194f0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
19500 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
19510 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
19520 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
19530 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19540 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
19550 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
19560 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
19570 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
19580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19590 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
195a0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
195b0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
195c0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
195d0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
195e0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
195f0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
19600 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
19610 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
19620 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
19630 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
19640 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
19650 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
19660 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
19670 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
19680 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
19690 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
196a0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
196b0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
196c0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
196d0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
196e0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
196f0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
19700 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
19710 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
19720 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
19730 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
19740 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
19750 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
19760 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
19770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
19780 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
19790 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
197a0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
197b0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
197c0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
197d0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
197e0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
197f0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
19800 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
19810 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
19820 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
19830 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
19840 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
19850 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
19860 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
19870 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
19880 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
19890 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
198a0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
198b0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
198c0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
198d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
198e0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
198f0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
19900 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19910 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
19920 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
19930 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
19940 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
19950 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
19960 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
19970 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
19980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19990 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
199a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
199b0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
199c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
199d0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
199e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
199f0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
19a00 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
19a10 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
19a20 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
19a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19a40 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
19a50 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
19a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19a70 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
19a80 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
19a90 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
19aa0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
19ab0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
19ac0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
19ad0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
19ae0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
19af0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19b00 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
19b10 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
19b20 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
19b30 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
19b40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
19b50 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
19b60 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
19b70 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
19b80 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
19b90 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
19ba0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
19bb0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
19bc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
19bd0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
19be0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
19bf0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
19c00 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
19c10 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
19c20 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
19c30 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
19c40 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
19c50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
19c60 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
19c70 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
19c80 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
19c90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
19ca0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
19cb0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
19cc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19cd0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
19ce0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
19cf0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
19d00 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
19d10 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
19d20 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
19d30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
19d40 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
19d50 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
19d60 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
19d70 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
19d80 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
19d90 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
19da0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
19db0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
19dc0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
19dd0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
19de0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
19df0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
19e00 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
19e10 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
19e20 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
19e30 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
19e40 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
19e50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
19e60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19e80 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
19e90 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
19ea0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
19eb0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
19ec0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
19ed0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
19ee0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
19ef0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
19f00 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
19f10 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
19f20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
19f30 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
19f40 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
19f50 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
19f60 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
19f70 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
19f80 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
19f90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19fa0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
19fb0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
19fc0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
19fd0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
19fe0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
19ff0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1a000 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1a010 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1a020 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1a030 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1a040 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1a050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a060 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1a070 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1a080 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1a090 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1a0a0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1a0b0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1a0c0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1a0d0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1a0e0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1a0f0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1a100 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1a110 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1a120 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1a130 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1a140 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1a150 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1a160 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1a170 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1a180 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1a190 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1a1a0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1a1b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a1c0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1a1d0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1a1e0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1a1f0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1a200 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1a210 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1a220 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1a230 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1a240 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1a250 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1a260 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1a270 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1a280 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1a290 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1a2a0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1a2b0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1a2c0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1a2d0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1a2e0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1a2f0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1a300 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1a310 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1a320 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1a330 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1a340 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1a350 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1a360 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1a370 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1a380 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1a390 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1a3a0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1a3b0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1a3c0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1a3d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1a3e0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1a3f0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1a400 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1a410 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1a420 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1a430 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1a440 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1a450 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1a460 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1a470 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1a480 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a490 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1a4a0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1a4b0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1a4c0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1a4d0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1a4e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1a4f0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1a500 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1a510 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1a520 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1a530 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1a540 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1a550 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1a560 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1a570 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1a580 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1a590 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1a5a0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1a5b0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1a5c0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1a5d0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1a5e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1a5f0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1a600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a610 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1a620 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1a630 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a640 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1a650 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1a660 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1a670 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1a680 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1a690 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1a6a0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1a6b0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1a6c0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1a6d0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1a6e0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1a6f0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1a700 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1a710 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1a720 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1a730 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1a740 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1a750 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1a760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a770 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1a780 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1a790 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1a7a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a7b0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1a7c0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1a7d0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1a7e0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1a7f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a800 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1a810 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1a820 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1a830 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1a840 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1a850 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1a860 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1a870 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1a880 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1a890 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1a8a0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1a8b0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1a8c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1a8d0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1a8e0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1a8f0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1a900 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1a910 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a920 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1a930 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1a940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a950 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1a960 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1a970 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1a980 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1a990 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1a9a0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1a9b0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1a9c0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1a9d0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1a9e0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1a9f0 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1aa00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1aa10 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1aa20 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1aa30 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1aa40 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
1aa50 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1aa60 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1aa70 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1aa80 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1aa90 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1aaa0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1aab0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1aac0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1aad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1aae0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1aaf0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1ab00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1ab10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1ab20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ab30 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1ab40 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1ab50 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1ab60 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1ab70 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1ab80 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1ab90 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1aba0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1abb0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1abc0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1abd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1abe0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1abf0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1ac00 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1ac10 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1ac20 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1ac30 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1ac40 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1ac50 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
1ac60 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
1ac70 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
1ac80 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1ac90 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1aca0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1acb0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1acc0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1acd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1ace0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1acf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1ad00 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1ad10 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1ad20 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1ad30 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1ad40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1ad50 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1ad60 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1ad70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ad80 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1ad90 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1ada0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1adb0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1adc0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1add0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1ade0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1adf0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1ae00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ae10 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1ae20 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1ae30 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1ae40 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1ae50 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1ae60 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1ae70 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1ae80 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1ae90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1aea0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1aeb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1aec0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1aed0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1aee0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1aef0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1af00 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1af10 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1af20 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1af30 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1af40 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1af50 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1af60 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1af70 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1af80 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1af90 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1afa0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1afb0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1afc0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1afd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1afe0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1aff0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1b000 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1b010 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1b020 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1b030 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1b040 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1b050 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1b060 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1b070 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1b080 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1b090 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1b0a0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1b0b0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1b0c0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1b0d0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1b0e0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1b0f0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1b100 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1b110 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1b130 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1b140 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1b150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b160 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1b170 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1b180 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b190 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b1a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1b0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1b1c0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1b1d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b1e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b1f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b200 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1b210 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1b220 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1b230 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b250 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1b260 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1b270 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b280 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b2a0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1b2b0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1b2c0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b2d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b2e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b2f0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1b300 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1b310 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b320 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b330 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b340 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1b350 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1b360 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b370 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b380 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b390 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1b3a0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1b3b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b3c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b3d0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1b3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1b3f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b400 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b410 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b420 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1b430 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1b440 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1b450 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1b460 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b470 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1b480 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1b490 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b4a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b4b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b4c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1b4d0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1b4e0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b4f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b500 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b510 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1b520 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1b530 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b540 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b550 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b560 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1b570 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1b580 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1b590 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b5a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b5b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1b5c0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1b5d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1b5e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b5f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b600 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1b610 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1b620 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b630 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b650 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1b660 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1b670 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b680 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b6a0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1b6b0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1b6c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b6d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b6e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1b6f0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1b700 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1b710 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1b720 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1b730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1b740 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1b750 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1b760 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1b770 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1b780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1b790 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1b7a0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1b7b0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1b7c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b7d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1b7e0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1b7f0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1b800 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1b810 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b820 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1b830 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1b840 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1b850 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1b860 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1b870 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1b880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b890 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1b8a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b8b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b8c0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1b8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1b8e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1b8f0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1b900 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b910 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1b920 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1b930 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1b940 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1b950 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b960 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1b970 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1b980 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1b990 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b9a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b9b0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1b9c0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1b9d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b9e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b9f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ba00 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1ba10 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1ba20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ba30 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1ba40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ba50 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1ba60 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1ba70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ba80 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1ba90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1baa0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1bab0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1bac0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1bad0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1bae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1baf0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1bb00 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1bb10 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1bb20 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1bb30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bb40 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1bb50 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1bb60 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1bb70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bb80 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
1bb90 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
1bba0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bbb0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
1bbc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1bbd0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
1bbe0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
1bbf0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
1bc00 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
1bc10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1bc20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1bc30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1bc40 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1bc50 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1bc60 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1bc70 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1bc80 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bc90 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1bca0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bcb0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
1bcc0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1bcd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
1bce0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
1bcf0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
1bd00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
1bd10 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
1bd20 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1bd30 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1bd40 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
1bd50 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1bd60 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
1bd70 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
1bd80 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
1bd90 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
1bda0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
1bdb0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
1bdc0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
1bdd0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
1bde0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
1bdf0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
1be00 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1be10 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1be20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
1be30 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
1be40 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
1be50 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1be60 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
1be70 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
1be80 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
1be90 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
1bea0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
1beb0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
1bec0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
1bed0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
1bee0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
1bef0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1bf00 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
1bf10 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
1bf20 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
1bf30 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
1bf40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
1bf50 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
1bf60 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
1bf70 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
1bf80 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
1bf90 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
1bfa0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
1bfb0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
1bfc0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1bfd0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
1bfe0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
1bff0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
1c000 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
1c010 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
1c020 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c030 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
1c040 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1c050 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
1c060 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1c070 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
1c080 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
1c090 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1c0a0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1c0b0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1c0c0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1c0d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1c0e0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1c0f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1c100 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1c110 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1c120 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1c130 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1c140 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1c150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1c160 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1c170 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1c180 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
1c190 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
1c1a0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
1c1b0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
1c1c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
1c1d0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
1c1e0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1c1f0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
1c200 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
1c210 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1c220 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1c230 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
1c240 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
1c250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c260 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
1c270 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1c280 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1c290 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1c2a0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1c2b0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1c2c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1c2d0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
1c2e0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
1c2f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c300 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
1c310 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
1c320 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
1c330 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
1c340 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
1c350 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
1c360 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
1c370 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
1c380 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
1c390 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
1c3a0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
1c3b0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1c3c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1c3d0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1c3e0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1c3f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c400 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1c410 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1c420 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1c430 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1c440 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1c450 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1c460 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1c470 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1c480 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c490 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1c4a0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1c4b0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1c4c0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1c4d0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1c4e0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1c4f0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1c500 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1c510 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1c520 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1c530 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1c540 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1c550 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1c560 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1c570 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1c580 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1c590 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1c5a0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1c5b0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1c5c0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1c5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c5e0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c5f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1c600 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1c610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c620 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1c630 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1c640 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1c650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c660 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1c670 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1c680 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1c690 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
1c6a0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c6b0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1c6c0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1c6d0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1c6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1c6f0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1c700 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1c710 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1c720 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1c730 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1c740 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1c750 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1c760 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1c770 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1c780 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1c790 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1c7a0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1c7b0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1c7c0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1c7d0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1c7e0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1c7f0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1c800 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1c810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c820 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1c830 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1c840 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1c850 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1c860 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1c870 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1c880 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1c890 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1c8a0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1c8b0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1c8c0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1c8d0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1c8e0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1c8f0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1c900 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1c910 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1c920 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1c930 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1c940 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1c950 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1c960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1c970 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1c980 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1c990 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1c9a0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1c9b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1c9c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1c9d0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1c9e0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1c9f0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1ca00 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1ca10 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1ca20 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1ca30 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1ca40 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1ca50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1ca60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1ca70 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1ca80 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1ca90 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1caa0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1cab0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1cac0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1cad0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1cae0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1caf0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1cb00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1cb10 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1cb20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1cb30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1cb40 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1cb50 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1cb60 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1cb70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1cb80 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1cb90 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1cba0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1cbb0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1cbc0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1cbd0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1cbe0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1cbf0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1cc00 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1cc10 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1cc20 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1cc30 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1cc40 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1cc50 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1cc60 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1cc70 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1cc80 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1cc90 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1cca0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1ccb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1ccc0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1ccd0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1cce0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1ccf0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1cd00 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1cd10 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1cd20 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1cd30 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1cd40 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1cd50 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1cd60 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1cd70 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
1cd80 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1cd90 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
1cda0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1cdb0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1cdc0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1cdd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1cde0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1cdf0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1ce00 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1ce10 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1ce20 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1ce30 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1ce40 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1ce50 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1ce60 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ce70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ce80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ce90 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1cea0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1ceb0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1cec0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1ced0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1cee0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1cef0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1cf00 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1cf10 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1cf20 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1cf30 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1cf40 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1cf50 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1cf60 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1cf70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1cf80 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1cf90 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1cfa0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1cfb0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1cfc0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1cfd0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1cfe0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
1cff0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1d000 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1d010 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1d020 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1d030 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1d040 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1d050 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
1d060 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
1d070 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1d080 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d090 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1d0a0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1d0b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1d0c0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
1d0d0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1d0e0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
1d0f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1d100 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
1d110 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
1d120 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1d130 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1d140 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1d150 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1d160 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1d170 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d180 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1d190 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1d1a0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1d1b0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1d1c0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1d1d0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1d1e0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1d1f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1d200 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1d210 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1d220 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1d230 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1d240 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d250 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1d260 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1d270 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1d280 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1d290 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1d2a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1d2b0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1d2c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1d2d0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1d2e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1d2f0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1d300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d310 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1d320 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1d330 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1d340 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1d350 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1d360 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1d370 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1d380 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1d390 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1d3a0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1d3b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1d3c0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1d3d0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1d3e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1d3f0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1d400 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1d410 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1d420 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1d430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1d440 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1d450 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d460 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1d470 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1d480 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1d490 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1d4a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1d4b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1d4c0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1d4d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1d4e0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1d4f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1d500 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1d510 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1d520 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d530 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1d540 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
1d550 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1d560 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1d570 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1d580 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1d590 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1d5a0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1d5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1d5c0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1d5d0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1d5e0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1d5f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d600 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1d610 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d620 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d630 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1d640 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1d650 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1d660 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1d670 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1d680 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1d690 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1d6a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1d6b0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1d6c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1d6d0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1d6e0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1d6f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1d700 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1d710 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1d720 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1d730 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1d740 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1d750 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1d760 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1d770 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1d780 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1d790 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1d7a0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1d7b0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1d7c0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1d7d0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1d7e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d7f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1d800 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
1d810 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
1d820 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
1d830 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
1d840 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
1d850 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
1d860 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1d870 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
1d880 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1d890 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
1d8a0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
1d8b0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
1d8c0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
1d8d0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
1d8e0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1d8f0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
1d900 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d910 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
1d920 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
1d930 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1d940 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d950 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
1d960 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
1d970 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
1d980 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
1d990 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
1d9a0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
1d9b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
1d9c0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
1d9d0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
1d9e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1d9f0 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
1da00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1da10 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
1da20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1da30 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
1da40 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
1da50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
1da60 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1da70 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
1da80 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
1da90 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
1daa0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
1dab0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
1dac0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1dad0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
1dae0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
1daf0 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
1db00 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
1db10 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
1db20 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
1db30 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
1db40 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
1db50 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
1db60 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
1db70 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
1db80 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
1db90 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
1dba0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
1dbb0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
1dbc0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
1dbd0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
1dbe0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
1dbf0 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
1dc00 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
1dc10 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1dc20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1dc30 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
1dc40 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
1dc50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
1dc60 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
1dc70 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
1dc80 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
1dc90 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
1dca0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
1dcb0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
1dcc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1dcd0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
1dce0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
1dcf0 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
1dd00 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
1dd10 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
1dd20 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
1dd30 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
1dd40 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
1dd50 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
1dd60 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
1dd70 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
1dd80 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
1dd90 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
1dda0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
1ddb0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
1ddc0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
1ddd0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
1dde0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
1ddf0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1de00 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
1de10 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1de20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
1de30 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
1de40 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
1de50 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
1de60 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
1de70 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
1de80 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
1de90 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
1dea0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
1deb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1dec0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1ded0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1dee0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
1def0 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
1df00 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
1df10 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
1df20 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
1df30 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
1df40 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
1df50 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1df60 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1df70 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
1df80 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
1df90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1dfa0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
1dfb0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
1dfc0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
1dfd0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
1dfe0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
1dff0 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
1e000 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
1e010 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
1e020 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
1e030 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e040 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
1e050 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
1e060 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
1e070 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
1e080 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
1e090 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
1e0a0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
1e0b0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
1e0c0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
1e0d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1e0e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1e0f0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1e100 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
1e110 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1e120 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
1e130 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 20  ther "ro", "rw" 
1e140 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2e  or.**     "rwc".
1e150 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
1e160 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
1e170 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  er value is an e
1e180 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
1e190 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
1e1a0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
1e1b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1e1c0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
1e1d0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
1e1e0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
1e1f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e200 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
1e210 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
1e220 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
1e230 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1e240 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20  3_prepare_v2(). 
1e250 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
1e260 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
1e270 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
1e280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e290 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1e2a0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
1e2b0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
1e2c0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
1e2d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1e2e0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
1e2f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
1e300 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
1e310 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
1e320 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
1e330 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
1e340 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
1e350 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e360 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
1e370 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c 69  CREATE. ^If sqli
1e380 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1e390 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20 69   .**     used, i
1e3a0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
1e3b0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
1e3c0 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70 61   for the mode pa
1e3d0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
1e3e0 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65 73  .**     less res
1e3f0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
1e400 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  at specified by 
1e410 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
1e420 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a   as the third .*
1e430 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e  *     parameter.
1e440 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1e450 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
1e460 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
1e470 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1e480 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
1e490 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
1e4a0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
1e4b0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
1e4c0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1e4d0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
1e4e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1e4f0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
1e500 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
1e510 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
1e520 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
1e530 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
1e540 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
1e550 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
1e560 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
1e570 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1e580 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
1e590 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
1e5a0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
1e5b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e5c0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
1e5d0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
1e5e0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
1e5f0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
1e600 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
1e610 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
1e620 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
1e630 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
1e640 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1e650 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
1e660 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1e670 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
1e680 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
1e690 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1e6a0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
1e6b0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
1e6c0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
1e6d0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
1e6e0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
1e6f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1e700 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
1e710 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
1e720 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
1e730 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
1e740 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
1e750 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
1e760 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
1e770 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1e780 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
1e790 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
1e7a0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
1e7b0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1e7c0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
1e7d0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
1e7e0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
1e7f0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
1e800 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
1e810 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
1e820 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1e830 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
1e840 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1e850 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
1e860 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1e870 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
1e880 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1e890 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1e8a0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
1e8b0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
1e8c0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
1e8d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1e8e0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
1e8f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1e900 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
1e910 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1e920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
1e930 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1e940 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
1e950 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
1e960 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1e970 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
1e980 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
1e990 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
1e9a0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
1e9b0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
1e9c0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
1e9d0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
1e9e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1e9f0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
1ea00 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
1ea10 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
1ea20 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
1ea30 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
1ea40 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
1ea50 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
1ea60 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
1ea70 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
1ea80 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
1ea90 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
1eaa0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
1eab0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
1eac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
1ead0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
1eae0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
1eaf0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
1eb00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
1eb10 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
1eb20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1eb30 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
1eb40 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
1eb50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1eb60 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
1eb70 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
1eb80 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
1eb90 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
1eba0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
1ebb0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1ebc0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1ebd0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
1ebe0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
1ebf0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
1ec00 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
1ec10 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
1ec20 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
1ec30 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
1ec40 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
1ec50 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
1ec60 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
1ec70 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
1ec80 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
1ec90 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
1eca0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1ecb0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
1ecc0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
1ecd0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1ece0 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
1ecf0 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
1ed00 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
1ed10 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
1ed20 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
1ed30 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
1ed40 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
1ed50 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
1ed60 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
1ed70 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
1ed80 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
1ed90 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
1eda0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
1edb0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
1edc0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
1edd0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
1ede0 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
1edf0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
1ee00 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
1ee10 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
1ee20 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
1ee30 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
1ee40 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
1ee50 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
1ee60 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
1ee70 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
1ee80 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
1ee90 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
1eea0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
1eeb0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
1eec0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
1eed0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
1eee0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
1eef0 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
1ef00 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
1ef10 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
1ef20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
1ef30 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1ef40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
1ef50 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1ef60 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1ef70 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1ef80 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1ef90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1efa0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1efb0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1efc0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1efd0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1efe0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1eff0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1f000 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1f010 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1f020 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1f030 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1f040 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1f050 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1f060 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1f070 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1f080 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f090 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f0a0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1f0b0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1f0c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1f0d0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1f0e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1f0f0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1f100 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1f110 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1f120 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1f130 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1f140 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1f150 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1f160 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1f170 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1f180 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1f190 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1f1a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1f1b0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1f1c0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1f1d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1f1e0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1f1f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1f200 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1f210 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1f220 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1f230 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1f240 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1f250 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1f260 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1f270 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1f280 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1f290 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
1f2a0 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
1f2b0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
1f2c0 2a 20 54 68 69 73 20 69 73 20 61 20 75 74 69 6c  * This is a util
1f2d0 69 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73 65  ity routine, use
1f2e0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
1f2f0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
1f300 20 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73 65   checks.** to se
1f310 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
1f320 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
1f330 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
1f340 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
1f350 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
1f360 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
1f370 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1f380 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1f390 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69 6c  ..**.** The zFil
1f3a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1f3b0 73 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 70  s the filename p
1f3c0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
1f3d0 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
1f3e0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56 46  * method of a VF
1f3f0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f400 2e 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61 72  .  The zParam ar
1f410 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 61  gument is the na
1f420 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75 65  me of the.** que
1f430 72 79 20 70 61 72 61 6d 65 74 65 72 20 77 65 20  ry parameter we 
1f440 73 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75 74  seek.  This rout
1f450 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1f460 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50 61  value of the zPa
1f470 72 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ram.** parameter
1f480 20 69 66 20 69 74 20 65 78 69 73 74 73 2e 20 20   if it exists.  
1f490 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1f4a0 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c   does not exist,
1f4b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
1f4c0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1f4d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  pointer..**.** I
1f4e0 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
1f4f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
1f500 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
1f510 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
1f520 53 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65 64  SQLite.** passed
1f530 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 20   into the xOpen 
1f540 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
1f550 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
1f560 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
1f570 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f580 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
1f590 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
1f5a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
1f5b0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
1f5c0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
1f5d0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
1f5e0 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  zParam);.../*.**
1f5f0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1f600 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1f610 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1f620 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1f630 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f640 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1f650 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1f660 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1f670 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1f680 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1f690 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1f6a0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1f6b0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1f6c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f6d0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1f6e0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1f6f0 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1f700 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1f710 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1f720 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1f730 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1f740 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1f750 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1f760 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1f770 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1f780 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1f790 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1f7a0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1f7b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1f7c0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1f7d0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1f7e0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1f7f0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1f800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1f810 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1f820 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1f830 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1f840 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1f850 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1f860 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1f870 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1f880 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1f890 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1f8a0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1f8b0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1f8c0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1f8d0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1f8e0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1f8f0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1f900 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1f910 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1f920 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1f930 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1f940 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1f950 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1f960 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1f970 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1f980 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1f990 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1f9a0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1f9b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1f9c0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1f9d0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1f9e0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1f9f0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1fa00 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1fa10 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1fa20 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1fa30 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1fa40 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1fa50 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1fa60 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1fa70 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1fa80 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1fa90 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1faa0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1fab0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1fac0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1fad0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1fae0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1faf0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1fb00 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1fb10 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1fb20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1fb30 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1fb40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1fb50 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1fb60 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1fb70 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1fb80 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1fb90 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1fba0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1fbb0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1fbc0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1fbd0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1fbe0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1fbf0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1fc00 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1fc10 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1fc20 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1fc30 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1fc40 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1fc50 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1fc60 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1fc70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1fc80 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1fc90 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1fca0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1fcb0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1fcc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1fcd0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1fce0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1fcf0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1fd00 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1fd10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1fd20 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1fd30 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1fd40 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1fd50 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1fd60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1fd70 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1fd80 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1fd90 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1fda0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1fdb0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1fdc0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1fdd0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1fde0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1fdf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1fe00 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1fe10 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1fe20 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1fe30 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1fe40 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1fe50 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1fe60 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1fe70 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1fe80 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1fe90 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1fea0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1feb0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1fec0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1fed0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1fee0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1fef0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1ff00 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1ff10 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1ff20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1ff30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1ff40 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1ff50 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1ff60 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1ff70 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1ff80 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1ff90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ffa0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1ffb0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1ffc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1ffd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1ffe0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1fff0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
20000 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
20010 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
20020 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
20030 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
20040 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
20050 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
20060 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
20070 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
20080 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
20090 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
200a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
200b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
200c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
200d0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
200e0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
200f0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
20100 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
20110 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
20120 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
20130 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
20140 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
20150 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
20160 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
20170 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
20180 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20190 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
201a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
201b0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
201c0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
201d0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
201e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
201f0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
20200 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
20210 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
20220 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
20230 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
20240 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
20250 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
20260 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
20270 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
20280 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
20290 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
202a0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
202b0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
202c0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
202d0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
202e0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
202f0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
20300 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
20310 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
20320 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
20330 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
20340 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
20350 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
20360 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
20370 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
20380 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
20390 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
203a0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
203b0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
203c0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
203d0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
203e0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
203f0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
20400 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
20410 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
20420 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
20430 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
20440 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
20450 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
20460 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
20470 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
20480 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
20490 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
204a0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
204b0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
204c0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
204d0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
204e0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
204f0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
20500 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
20510 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
20520 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
20530 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
20540 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
20550 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
20560 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
20570 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
20580 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
20590 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
205a0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
205b0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
205c0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
205d0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
205e0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
205f0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
20600 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
20610 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
20620 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
20630 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
20640 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
20650 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
20660 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
20670 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
20680 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
20690 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
206a0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
206b0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
206c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
206d0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
206e0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
206f0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
20700 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
20710 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
20720 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
20730 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
20740 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
20750 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
20760 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
20770 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
20780 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
20790 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
207a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
207b0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
207c0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
207d0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
207e0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
207f0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
20800 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
20810 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
20820 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
20830 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
20840 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
20850 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
20860 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
20870 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
20880 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
20890 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
208a0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
208b0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
208c0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
208d0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
208e0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
208f0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
20900 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
20910 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
20920 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
20930 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
20940 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
20950 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
20960 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
20970 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
20980 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
20990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
209a0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
209b0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
209c0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
209d0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
209e0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
209f0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
20a00 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
20a10 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
20a20 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
20a30 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
20a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
20a50 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
20a60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
20a70 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
20a80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
20a90 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
20aa0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
20ab0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
20ac0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
20ad0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
20ae0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
20af0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
20b00 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
20b10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
20b20 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
20b30 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
20b40 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
20b50 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
20b60 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
20b70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
20b80 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
20b90 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
20ba0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
20bb0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
20bc0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
20bd0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
20be0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
20bf0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20c00 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
20c10 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
20c20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
20c30 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
20c40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
20c60 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
20c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
20c80 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
20c90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
20ca0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
20cb0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
20cc0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
20cd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
20ce0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
20cf0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
20d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
20d10 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
20d20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20d30 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
20d40 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
20d50 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
20d60 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
20d70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
20d80 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
20d90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
20da0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
20db0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
20dc0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
20dd0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
20de0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
20df0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
20e00 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
20e10 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
20e20 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
20e30 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
20e40 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
20e50 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
20e60 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
20e70 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
20e80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
20ea0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
20eb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
20ec0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
20ed0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20ee0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
20ef0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
20f00 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
20f10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
20f20 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
20f30 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20f40 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
20f50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20f60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
20f70 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
20f80 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
20f90 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
20fa0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
20fb0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
20fc0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
20fd0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
20fe0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
20ff0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
21000 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
21010 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
21020 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
21030 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
21040 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
21050 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21060 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
21070 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
21080 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
21090 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
210a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
210b0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
210c0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
210d0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
210e0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
210f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
21100 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
21110 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
21120 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
21130 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
21140 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
21150 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
21160 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
21170 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
21180 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
21190 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
211a0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
211b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
211c0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
211d0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
211e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
211f0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
21200 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
21210 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21220 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
21230 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
21240 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21250 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
21260 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
21270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
21280 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
21290 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
212a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
212b0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
212c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
212d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
212e0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
212f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
21300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21310 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
21320 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
21330 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
21340 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
21350 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
21360 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
21370 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
21380 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
21390 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
213a0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
213b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
213c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
213d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
213e0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
213f0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
21400 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
21410 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
21420 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
21430 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
21440 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
21450 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
21460 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
21470 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
21480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21490 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
214a0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
214b0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
214c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
214d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
214e0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
214f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
21500 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
21510 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
21520 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
21530 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
21540 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
21550 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
21560 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
21570 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
21580 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
21590 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
215a0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
215b0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
215c0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
215d0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
215e0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
215f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
21600 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
21610 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
21620 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
21630 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
21640 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
21650 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
21660 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
21670 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
21680 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
21690 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
216a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
216b0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
216c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
216d0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
216e0 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
216f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21700 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
21710 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
21720 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
21730 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
21740 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
21750 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
21760 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
21770 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
21780 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
21790 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
217a0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
217b0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
217c0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
217d0 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
217e0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
217f0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
21800 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
21810 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
21820 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
21830 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
21840 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
21850 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
21860 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
21870 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
21880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
21890 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
218a0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
218b0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
218c0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
218d0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
218e0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
218f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
21900 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
21910 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
21920 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
21930 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
21940 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
21950 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
21960 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
21970 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
21980 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
21990 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
219a0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
219b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
219c0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
219d0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
219e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
219f0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
21a00 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
21a10 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
21a20 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
21a30 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
21a40 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
21a50 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
21a60 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
21a70 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
21a80 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
21a90 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
21aa0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
21ab0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
21ac0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
21ad0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
21ae0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
21af0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21b00 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
21b10 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
21b20 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
21b30 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
21b40 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
21b50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
21b60 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
21b70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
21b80 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
21b90 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
21ba0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
21bb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
21bc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21bd0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
21be0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
21bf0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
21c00 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
21c10 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
21c20 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
21c30 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
21c40 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
21c50 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
21c60 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
21c70 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
21c80 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
21c90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21ca0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
21cb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
21cc0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
21cd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
21ce0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
21cf0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
21d00 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
21d10 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
21d20 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
21d30 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
21d40 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
21d50 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
21d60 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
21d70 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
21d80 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
21d90 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
21da0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
21db0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
21dc0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
21dd0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
21de0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
21df0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
21e00 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
21e10 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
21e20 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
21e30 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
21e40 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
21e50 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
21e60 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
21e70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
21e80 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
21e90 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
21ea0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
21eb0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
21ec0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
21ed0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
21ee0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
21ef0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
21f00 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
21f10 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
21f20 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
21f30 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
21f40 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
21f50 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
21f60 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
21f70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21f80 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
21f90 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
21fa0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
21fb0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
21fc0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
21fd0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
21fe0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
21ff0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
22000 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
22010 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
22020 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
22030 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
22040 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
22050 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
22060 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
22070 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
22080 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
22090 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
220a0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
220b0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
220c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
220d0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
220e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
220f0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
22100 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
22110 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
22120 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
22130 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
22140 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
22150 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
22160 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
22170 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
22180 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
22190 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
221a0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
221b0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
221c0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
221d0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
221e0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
221f0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
22200 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
22210 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
22220 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
22230 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
22240 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
22250 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
22260 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
22270 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
22280 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
22290 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69  BLE_STAT2] compi
222a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
222b0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
222c0 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
222d0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
222e0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
222f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
22300 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
22310 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
22320 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
22330 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
22340 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
22350 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22360 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22370 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22380 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22390 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
223a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
223b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
223c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
223d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
223e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
223f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
22400 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
22410 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
22420 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22430 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
22440 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22450 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22460 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22470 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22490 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
224a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
224b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
224c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
224d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
224e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
224f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
22500 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
22510 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
22520 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
22530 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
22540 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
22550 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
22560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22570 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
22580 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22590 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
225a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
225b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
225c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
225d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
225e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
225f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22600 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22610 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
22620 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22630 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22640 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22650 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22660 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
22670 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22680 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22690 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
226a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
226b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
226c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
226d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
226e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
226f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
22700 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22710 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22720 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
22730 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
22740 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
22750 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
22760 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
22770 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
22780 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
22790 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
227a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
227b0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
227c0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
227d0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
227e0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
227f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22800 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
22810 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
22820 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
22830 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
22840 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
22850 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
22860 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
22870 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
22880 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
22890 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
228a0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
228b0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
228c0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
228d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
228e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
228f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
22900 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22910 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
22920 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
22930 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
22940 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
22950 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
22960 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
22970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22980 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
22990 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
229a0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
229b0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
229c0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
229d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
229e0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
229f0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
22a00 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
22a10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
22a20 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
22a30 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
22a40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22a50 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
22a60 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
22a70 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
22a80 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
22a90 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
22aa0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
22ab0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
22ac0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
22ad0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
22ae0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
22af0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
22b00 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
22b10 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
22b20 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
22b30 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
22b40 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
22b50 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
22b60 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
22b70 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
22b80 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
22b90 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
22ba0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
22bb0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
22bc0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
22bd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
22be0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
22bf0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
22c00 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
22c10 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
22c20 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
22c30 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
22c40 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
22c50 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
22c60 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
22c70 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
22c80 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
22c90 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
22ca0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
22cb0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
22cc0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
22cd0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
22ce0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
22cf0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
22d00 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
22d10 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
22d20 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
22d30 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
22d40 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
22d50 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
22d60 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
22d70 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
22d80 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
22d90 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
22da0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
22db0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
22dc0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
22dd0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
22de0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
22df0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
22e00 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
22e10 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
22e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
22e30 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
22e40 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
22e50 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
22e60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
22e70 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
22e80 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
22e90 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
22ea0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
22eb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
22ec0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
22ed0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
22ee0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
22ef0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22f00 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
22f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
22f20 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
22f30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
22f40 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
22f50 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
22f60 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
22f70 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
22f80 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
22f90 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
22fa0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
22fb0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
22fc0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
22fd0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
22fe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
22ff0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
23000 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
23010 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
23020 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
23030 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
23040 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
23050 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
23060 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
23070 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
23080 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
23090 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
230a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
230b0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
230c0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
230d0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
230e0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
230f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23100 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
23110 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
23120 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
23130 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
23140 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
23150 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
23160 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
23170 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
23190 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
231a0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
231b0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
231c0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
231d0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
231e0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
231f0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
23200 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
23210 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
23220 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
23230 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
23240 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
23250 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
23260 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
23270 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
23280 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
23290 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
232a0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
232b0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
232c0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
232d0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
232e0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
232f0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
23300 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
23310 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
23320 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
23330 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
23340 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
23350 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
23360 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
23370 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
23380 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
23390 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
233a0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
233b0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
233c0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
233d0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
233e0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
233f0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
23400 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
23410 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
23420 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
23430 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
23440 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
23450 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
23460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23470 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
23480 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
23490 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
234a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
234b0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
234c0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
234d0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
234e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
234f0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
23500 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23510 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
23520 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
23530 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23540 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
23550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23560 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
23570 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
23580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23590 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
235a0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
235b0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
235c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
235d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
235e0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
235f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
23600 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
23610 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
23620 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
23630 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
23640 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
23650 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23660 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
23670 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
23680 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
23690 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
236a0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
236b0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
236c0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
236d0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
236e0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
236f0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
23700 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
23710 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
23720 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
23730 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
23740 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
23750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
23760 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
23770 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
23780 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
23790 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
237a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
237b0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
237c0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
237d0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
237e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
237f0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
23800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
23810 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
23820 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
23830 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
23840 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
23850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
23860 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
23870 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
23880 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
23890 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
238a0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
238b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
238c0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
238d0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
238e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
238f0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
23900 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
23910 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
23920 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
23930 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23940 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
23950 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
23960 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
23970 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
23980 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
23990 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
239a0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
239b0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
239c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
239d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
239e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
239f0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
23a00 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
23a10 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
23a20 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
23a30 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
23a40 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
23a50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
23a60 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
23a70 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
23a80 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
23a90 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
23aa0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
23ab0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
23ac0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
23ad0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
23ae0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
23af0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
23b00 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
23b10 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
23b20 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
23b30 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
23b40 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
23b50 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
23b60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
23b70 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
23b80 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
23b90 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
23ba0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
23bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
23bc0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
23bd0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23be0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
23bf0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
23c00 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
23c10 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
23c20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
23c30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23c40 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
23c50 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
23c60 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
23c70 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
23c80 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
23c90 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
23ca0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
23cb0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
23cc0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
23cd0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
23ce0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
23cf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
23d00 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
23d10 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
23d20 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
23d30 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
23d40 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
23d50 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
23d60 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
23d70 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
23d80 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
23d90 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
23da0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
23db0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23dc0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
23dd0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
23de0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
23df0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
23e00 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
23e10 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
23e20 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
23e30 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
23e40 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
23e50 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
23e60 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
23e70 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
23e80 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
23e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
23ea0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
23eb0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
23ec0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
23ed0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
23ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
23ef0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
23f00 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
23f10 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
23f20 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23f30 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
23f40 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
23f50 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
23f60 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
23f70 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
23f80 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
23f90 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23fa0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
23fb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
23fc0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
23fd0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
23fe0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
23ff0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24000 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
24010 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
24020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
24030 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
24040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
24050 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
24060 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
24070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24080 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
24090 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
240a0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
240b0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
240c0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
240d0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
240e0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
240f0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
24100 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
24110 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
24120 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
24130 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
24140 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
24150 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
24160 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
24170 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
24180 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
24190 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
241a0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
241b0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
241c0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
241d0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
241e0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
241f0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
24200 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
24210 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
24220 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
24230 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
24240 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
24250 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
24260 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
24270 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
24280 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
24290 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
242a0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
242b0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
242c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
242d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
242e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
242f0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
24300 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
24310 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
24320 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
24330 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
24340 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
24350 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
24360 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
24370 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
24380 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
24390 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
243a0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
243b0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
243c0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
243d0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
243e0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
243f0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
24400 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
24410 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
24420 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
24430 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
24440 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
24450 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
24460 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
24470 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
24480 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
24490 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
244a0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
244b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
244c0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
244d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
244e0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
244f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24500 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
24510 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
24520 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
24530 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
24540 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
24550 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
24560 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
24570 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
24580 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
24590 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
245a0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
245b0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
245c0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
245d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
245e0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
245f0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
24600 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
24610 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
24620 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
24630 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
24640 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
24650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
24660 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
24670 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
24680 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
24690 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
246a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
246b0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
246c0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
246d0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
246e0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
246f0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
24700 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
24710 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
24720 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
24730 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
24740 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
24750 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
24760 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
24770 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
24780 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
24790 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
247a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
247b0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
247c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
247d0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
247e0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
247f0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
24800 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
24810 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
24820 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24830 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
24840 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
24850 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
24860 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
24870 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24880 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
24890 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
248a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
248b0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
248c0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
248d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
248e0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
248f0 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
24900 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
24910 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
24920 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24930 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
24940 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
24950 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
24960 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
24970 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24980 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
24990 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
249a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
249b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
249c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
249d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
249e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
249f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24a10 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
24a20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
24a30 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
24a40 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
24a50 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
24a60 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
24a70 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
24a80 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
24a90 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
24aa0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
24ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24ac0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
24ad0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
24ae0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
24af0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
24b00 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
24b10 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
24b20 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
24b30 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
24b40 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
24b50 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
24b60 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
24b70 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
24b80 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
24b90 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
24ba0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
24bb0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
24bc0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
24bd0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
24be0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
24bf0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
24c00 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
24c10 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
24c20 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
24c30 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
24c40 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
24c50 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
24c60 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
24c70 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
24c80 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
24c90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24ca0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
24cb0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
24cc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24cd0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
24ce0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
24cf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
24d00 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
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 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
24d30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
24d40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
24d50 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
24d60 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
24d70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
24d80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
24d90 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
24da0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
24db0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
24dc0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
24dd0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24de0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
24df0 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
24e00 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
24e10 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
24e20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
24e30 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
24e40 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
24e50 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
24e60 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
24e70 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
24e80 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
24e90 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
24ea0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
24eb0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
24ec0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
24ed0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
24ee0 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
24ef0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
24f00 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
24f10 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
24f20 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
24f30 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
24f40 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
24f50 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
24f60 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
24f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
24f80 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
24f90 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
24fa0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
24fb0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
24fc0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
24fd0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
24fe0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
24ff0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
25000 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
25010 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
25020 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
25030 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
25040 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
25050 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
25060 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
25070 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
25080 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
25090 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
250a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
250b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
250c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
250d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
250e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
250f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
25100 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
25110 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
25120 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25130 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
25140 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
25150 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
25160 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
25170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
25180 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25190 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
251a0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
251b0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
251c0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
251d0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
251e0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
251f0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
25200 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
25210 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
25220 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
25230 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
25240 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
25250 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
25260 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
25270 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
25280 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
25290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
252a0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
252b0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
252c0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
252d0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
252e0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
252f0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
25300 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
25310 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
25320 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25330 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25340 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
25350 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
25360 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
25370 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25380 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
25390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
253a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
253b0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
253c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
253d0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
253e0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
253f0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
25400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
25410 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
25420 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
25430 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
25440 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
25450 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
25460 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
25470 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
25480 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
25490 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
254a0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
254b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
254c0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
254d0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
254e0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
254f0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
25500 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
25510 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
25520 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
25530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
25540 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
25550 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
25560 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
25570 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
25580 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
25590 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
255a0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
255b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
255c0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
255d0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
255e0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
255f0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
25600 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
25610 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
25620 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
25630 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
25640 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
25650 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
25660 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
25670 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25680 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25690 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
256a0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
256b0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
256c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
256d0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
256e0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
256f0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
25700 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
25710 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
25720 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
25730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
25740 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
25750 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
25760 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
25770 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
25780 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
25790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
257a0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
257b0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
257c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
257d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
257e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
257f0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
25800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
25810 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
25820 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
25830 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
25840 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
25850 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
25860 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
25870 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
25880 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
25890 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
258a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
258b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
258c0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
258d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
258e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
258f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25900 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
25910 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
25920 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
25930 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
25940 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
25950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25960 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
25970 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
25980 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
25990 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
259a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
259b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
259c0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
259d0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
259e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
259f0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
25a00 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
25a10 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
25a20 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
25a30 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
25a40 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
25a50 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
25a60 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
25a70 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
25a80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
25a90 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
25aa0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
25ab0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
25ac0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
25ad0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
25ae0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
25af0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
25b00 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
25b10 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
25b20 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
25b30 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
25b40 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
25b50 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
25b60 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
25b70 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
25b80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25b90 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
25ba0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
25bb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25bc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
25bd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25be0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
25bf0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
25c00 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
25c10 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
25c20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
25c30 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
25c40 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
25c50 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
25c60 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
25c70 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
25c80 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
25c90 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
25ca0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
25cb0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25cc0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
25cd0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
25ce0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
25cf0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
25d00 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
25d10 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
25d20 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
25d30 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
25d40 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
25d50 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
25d60 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
25d70 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
25d80 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
25d90 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
25da0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
25db0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
25dc0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
25dd0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
25de0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
25df0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25e00 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
25e10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
25e20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
25e30 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
25e40 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
25e50 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
25e60 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
25e70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25e80 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
25e90 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
25ea0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
25eb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
25ec0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
25ed0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
25ee0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
25ef0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
25f00 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
25f10 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
25f20 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
25f30 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
25f40 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
25f50 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
25f60 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
25f70 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
25f80 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25f90 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
25fa0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
25fb0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
25fc0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
25fd0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
25fe0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
25ff0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
26000 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
26010 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
26020 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
26030 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
26040 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
26050 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
26060 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
26070 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
26080 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26090 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
260a0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
260b0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
260c0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
260d0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
260e0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
260f0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
26100 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
26110 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
26120 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
26130 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
26140 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
26150 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
26160 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
26170 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
26180 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
26190 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
261a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
261b0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
261c0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
261d0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
261e0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
261f0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
26200 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
26210 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26220 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
26230 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
26240 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
26250 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
26260 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
26270 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
26280 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
26290 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
262a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
262b0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
262c0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
262d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
262e0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
262f0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
26300 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
26310 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
26320 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
26330 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
26340 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
26350 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
26360 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
26370 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
26380 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
26390 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
263a0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
263b0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
263c0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
263d0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
263e0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
263f0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
26400 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
26410 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
26420 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
26430 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
26440 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
26450 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
26460 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
26470 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
26480 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
26490 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
264a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
264b0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
264c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
264d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
264e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
264f0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
26500 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
26510 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26520 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
26530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26540 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
26550 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26560 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
26570 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
26580 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
265a0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
265b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
265c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
265d0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
265e0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
265f0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
26600 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
26610 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26620 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
26630 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
26640 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
26650 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
26660 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
26670 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
26680 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
26690 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
266a0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
266b0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
266c0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
266d0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
266e0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
266f0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
26700 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
26710 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
26720 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26730 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
26740 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
26750 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
26760 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
26770 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
26780 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
26790 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
267a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
267b0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
267c0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
267d0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
267e0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
267f0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
26800 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
26810 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26820 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
26830 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
26840 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
26850 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
26860 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
26870 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
26880 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
26890 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
268a0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
268b0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
268c0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
268d0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
268e0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
268f0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
26900 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
26910 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
26920 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
26930 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
26940 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
26950 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
26960 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
26970 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
26980 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
26990 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
269a0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
269b0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
269c0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
269d0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
269e0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
269f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26a00 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
26a10 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
26a20 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
26a30 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
26a40 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
26a50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26a60 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
26a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26a80 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
26a90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26aa0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
26ab0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
26ac0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ad0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
26ae0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
26af0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
26b00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
26b10 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
26b20 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
26b30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26b40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
26b50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26b60 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
26b70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26b80 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
26b90 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
26ba0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26bb0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
26bc0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
26bd0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
26be0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
26bf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
26c00 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
26c10 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
26c20 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
26c30 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
26c40 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
26c50 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
26c60 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
26c70 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
26c80 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
26c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26ca0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
26cb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26cc0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
26cd0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
26ce0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
26cf0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
26d00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26d10 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
26d20 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
26d30 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
26d40 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
26d50 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26d60 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
26d70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
26d80 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
26d90 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
26da0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
26db0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
26dc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
26dd0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
26de0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
26df0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
26e00 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
26e10 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
26e20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
26e30 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
26e40 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
26e50 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
26e60 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
26e70 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
26e80 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
26e90 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
26ea0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
26eb0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
26ec0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
26ed0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
26ee0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
26ef0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
26f00 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
26f10 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
26f20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
26f30 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
26f40 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
26f50 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
26f60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
26f70 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
26f80 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
26f90 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
26fa0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
26fb0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
26fc0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
26fd0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
26fe0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
26ff0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
27000 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
27010 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
27020 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
27030 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
27040 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
27050 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
27060 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
27070 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
27080 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
27090 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
270a0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
270b0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
270c0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
270d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
270e0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
270f0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
27100 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
27110 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
27120 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
27130 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27140 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
27150 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
27160 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
27170 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
27180 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
27190 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
271a0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
271b0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
271c0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
271d0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
271e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
271f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
27200 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
27210 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
27220 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
27230 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
27240 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
27250 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
27260 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
27270 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
27280 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
27290 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
272a0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
272b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
272c0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
272d0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
272e0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
272f0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
27300 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
27310 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
27320 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
27330 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
27340 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
27350 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
27360 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
27370 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
27380 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
27390 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
273a0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
273b0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
273c0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
273d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
273e0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
273f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27400 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
27410 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
27420 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
27430 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
27440 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
27450 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
27460 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
27470 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
27480 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
27490 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
274a0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
274b0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
274c0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
274d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
274e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
274f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
27500 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27510 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
27520 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
27530 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
27540 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
27550 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
27560 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
27570 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
27580 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
27590 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
275a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
275b0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
275c0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
275d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
275e0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
275f0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
27600 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
27610 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
27620 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
27630 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
27640 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
27650 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
27660 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
27670 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
27680 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
27690 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
276a0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
276b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
276c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
276d0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
276e0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
276f0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
27700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
27710 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
27720 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
27730 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
27740 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
27750 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
27760 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
27770 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
27780 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
27790 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
277a0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
277b0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
277c0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
277d0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
277e0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
277f0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
27800 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
27810 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
27820 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
27830 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
27840 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
27850 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
27860 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
27870 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
27880 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
27890 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
278a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
278b0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
278c0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
278d0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
278e0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
278f0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
27900 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
27910 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
27920 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
27930 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
27940 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
27950 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
27960 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
27970 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
27980 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
27990 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
279a0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
279b0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
279c0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
279d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
279e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
279f0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
27a00 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
27a10 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
27a20 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
27a30 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
27a40 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
27a50 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
27a60 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
27a70 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
27a80 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
27a90 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
27aa0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
27ab0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
27ac0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
27ad0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
27ae0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
27af0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
27b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27b10 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
27b20 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
27b30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27b40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27b50 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
27b60 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
27b70 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
27b80 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
27b90 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
27ba0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
27bb0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
27bc0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
27bd0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
27be0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
27bf0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
27c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27c20 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
27c30 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
27c40 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
27c50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27c60 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
27c70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
27c80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
27c90 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
27ca0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
27cb0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
27cc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
27cd0 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
27ce0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
27cf0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
27d00 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
27d10 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
27d20 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
27d30 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
27d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
27d50 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
27d60 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
27d70 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
27d80 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
27d90 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
27da0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
27db0 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
27dc0 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
27dd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ter..**.** See a
27de0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
27df0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
27e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
27e10 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
27e20 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
27e40 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
27e50 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
27e60 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
27e70 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
27e80 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
27e90 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
27ea0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
27eb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
27ec0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
27ed0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
27ee0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
27ef0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
27f00 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
27f10 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
27f20 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
27f30 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
27f40 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
27f50 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
27f60 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
27f70 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
27f80 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
27f90 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
27fa0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
27fb0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
27fc0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
27fd0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
27fe0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
27ff0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
28000 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
28010 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
28020 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
28030 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
28040 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
28050 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
28060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
28070 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
28080 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
28090 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
280a0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
280b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
280c0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
280d0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
280e0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
280f0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
28100 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
28110 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
28120 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
28130 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
28140 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
28150 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
28160 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
28170 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
28180 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
28190 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
281a0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
281b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
281c0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
281d0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
281e0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
281f0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
28200 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
28210 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
28220 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
28230 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
28240 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
28250 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
28260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28270 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
28280 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
28290 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
282a0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
282b0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
282c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
282d0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
282e0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
282f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
28300 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
28310 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
28320 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
28330 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
28340 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
28350 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
28360 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28370 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
28380 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
28390 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
283a0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
283b0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
283c0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
283d0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
283e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
283f0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
28400 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
28410 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
28420 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
28430 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
28440 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
28450 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
28460 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
28470 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
28480 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
28490 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
284a0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
284b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
284c0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
284d0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
284e0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
284f0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
28500 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28510 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
28520 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
28530 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
28540 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
28550 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
28560 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28570 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
28580 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
28590 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
285a0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
285b0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
285c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
285d0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
285e0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
285f0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
28600 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
28610 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28620 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
28630 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
28640 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
28650 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
28660 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
28670 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
28680 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
28690 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
286a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
286b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
286c0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
286d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
286e0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
286f0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
28700 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
28710 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
28720 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
28730 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
28740 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
28750 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
28760 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
28770 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
28780 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
28790 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
287a0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
287b0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
287c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
287d0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
287e0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
287f0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
28800 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
28810 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
28820 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
28830 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
28840 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
28850 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
28860 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
28870 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
28880 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
28890 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
288a0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
288b0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
288c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
288d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
288e0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
288f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
28900 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
28910 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
28920 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
28930 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
28940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28960 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
28970 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
28980 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
28990 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
289a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
289b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
289c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
289d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
289e0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
289f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28a00 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
28a10 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
28a20 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
28a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28a40 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
28a50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
28a60 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
28a70 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
28a80 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
28a90 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
28aa0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28ab0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
28ac0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
28ad0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
28ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28af0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
28b00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
28b10 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
28b20 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
28b30 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
28b40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28b50 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
28b60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
28b70 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28b80 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
28b90 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
28ba0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
28bb0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
28bc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28bd0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
28be0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
28bf0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
28c00 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
28c10 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
28c20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
28c30 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
28c40 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
28c50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
28c60 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
28c70 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
28c80 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
28c90 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
28ca0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
28cb0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28cc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
28cd0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28ce0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
28cf0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
28d00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28d10 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
28d20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
28d30 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
28d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28d50 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
28d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28d70 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
28d80 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
28d90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
28da0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
28db0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
28dc0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
28dd0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
28de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28df0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
28e00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28e10 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
28e20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
28e30 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
28e40 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
28e50 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
28e60 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
28e70 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
28e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28e90 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
28ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28eb0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
28ec0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
28ed0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
28ee0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
28ef0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
28f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28f10 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
28f20 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
28f30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
28f40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
28f50 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
28f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28f70 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
28f80 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28f90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28fa0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
28fb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28fc0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
28fd0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
28fe0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
28ff0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
29000 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
29010 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
29020 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
29030 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29040 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
29050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29060 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
29070 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
29080 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
29090 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
290a0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
290b0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
290c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
290d0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
290e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
290f0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
29100 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29110 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
29120 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
29130 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
29140 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
29150 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
29160 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
29170 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
29180 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
29190 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
291a0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
291b0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
291c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
291d0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
291e0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
291f0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
29200 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
29210 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
29220 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
29230 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
29240 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
29250 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
29260 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
29270 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
29280 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
29290 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
292a0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
292b0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
292c0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
292d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
292e0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
292f0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
29300 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
29310 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
29320 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
29330 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
29340 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
29350 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
29360 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
29370 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
29380 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
29390 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
293a0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
293b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
293c0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
293d0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
293e0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
293f0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
29400 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
29410 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
29420 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
29430 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
29440 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
29450 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
29460 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
29470 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
29480 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
29490 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
294a0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
294b0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
294c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
294d0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
294e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
294f0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
29500 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
29510 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
29520 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29530 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
29540 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
29550 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29560 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
29570 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
29580 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29590 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
295a0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
295b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
295c0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
295d0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
295e0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
295f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
29600 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
29610 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
29620 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
29630 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
29640 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
29650 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
29660 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
29670 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
29680 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
29690 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
296a0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
296b0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
296c0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
296d0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
296e0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
296f0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
29700 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
29710 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
29720 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
29730 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
29740 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
29750 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
29760 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
29770 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
29780 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
29790 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
297a0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
297b0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
297c0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
297d0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
297e0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
297f0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
29800 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
29810 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
29820 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
29830 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
29840 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
29850 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
29860 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
29870 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
29880 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29890 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
298a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
298b0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
298c0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
298d0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
298e0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
298f0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
29900 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
29910 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
29920 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
29930 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
29940 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
29950 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
29960 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
29970 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29980 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
29990 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
299a0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
299b0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
299c0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
299d0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
299e0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
299f0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
29a00 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
29a10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29a20 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
29a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29a40 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
29a50 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
29a60 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
29a70 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
29a80 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
29a90 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
29aa0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
29ab0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
29ac0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
29ad0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
29ae0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
29af0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
29b00 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
29b10 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
29b20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
29b30 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
29b40 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
29b50 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
29b60 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
29b70 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
29b80 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
29b90 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
29ba0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
29bb0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
29bc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
29bd0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
29be0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
29bf0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
29c00 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
29c10 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
29c20 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
29c30 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
29c40 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
29c50 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
29c60 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
29c70 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
29c80 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
29c90 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
29ca0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
29cb0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
29cc0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
29cd0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
29ce0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
29cf0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
29d00 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
29d10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
29d20 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
29d30 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
29d40 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
29d50 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
29d60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
29d70 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
29d80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
29d90 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
29da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29db0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
29dc0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
29dd0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
29de0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29df0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
29e00 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
29e10 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
29e20 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
29e30 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
29e40 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
29e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
29e60 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
29e70 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
29e80 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
29e90 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
29ea0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
29eb0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
29ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29ed0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
29ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29ef0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
29f00 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
29f10 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
29f20 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
29f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29f40 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
29f50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
29f60 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
29f70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29f80 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
29f90 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
29fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29fb0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
29fc0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
29fd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
29fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
29ff0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2a000 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2a010 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2a020 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2a030 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2a040 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2a050 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2a060 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2a070 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2a080 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2a090 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2a0a0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2a0b0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2a0c0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2a0d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2a0e0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2a0f0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2a100 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2a110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2a120 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2a130 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2a140 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2a150 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2a160 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2a170 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2a180 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2a190 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2a1a0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2a1b0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2a1c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2a1d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2a1e0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2a1f0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2a200 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2a210 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2a220 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2a230 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2a240 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2a250 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2a260 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2a270 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2a280 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2a290 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a2a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2a2b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a2c0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2a2d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2a2e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a2f0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2a300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a310 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a320 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2a330 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2a340 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2a350 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a360 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2a370 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2a380 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a390 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2a3a0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2a3b0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2a3c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a3d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2a3e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2a3f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2a400 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a410 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2a420 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a430 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2a440 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a450 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a460 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2a470 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a480 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2a490 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a4a0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2a4b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a4c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a4d0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2a4e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2a4f0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2a500 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2a510 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2a520 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2a530 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a540 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2a550 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2a560 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2a570 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2a580 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2a590 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2a5a0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2a5b0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2a5c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2a5d0 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2a5e0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2a5f0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2a600 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2a610 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2a620 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2a630 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a640 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2a650 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2a660 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2a670 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a680 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2a690 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a6a0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2a6b0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2a6c0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2a6d0 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2a6e0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2a6f0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2a700 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2a710 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2a720 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2a730 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2a740 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2a750 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2a760 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2a770 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2a780 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2a790 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2a7a0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2a7b0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2a7c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2a7d0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2a7e0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2a7f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2a800 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2a810 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2a820 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2a830 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2a840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2a850 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2a860 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2a870 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2a880 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2a890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2a8a0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2a8b0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2a8c0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2a8d0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2a8e0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2a8f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2a900 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2a910 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2a920 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2a930 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2a940 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2a950 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2a960 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2a970 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2a980 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2a990 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2a9a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a9b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2a9c0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2a9d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2a9e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a9f0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2aa00 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2aa10 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2aa20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2aa30 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2aa40 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2aa50 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2aa60 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2aa70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2aa80 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2aa90 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2aaa0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2aab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2aac0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2aad0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2aae0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2aaf0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2ab00 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2ab10 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2ab20 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2ab30 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2ab40 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2ab50 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2ab60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ab70 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2ab80 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2ab90 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2aba0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2abb0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2abc0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2abd0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2abe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abf0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2ac00 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2ac10 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2ac20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2ac30 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2ac40 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2ac50 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2ac60 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2ac70 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2ac80 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2ac90 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2aca0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2acb0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2acc0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2acd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ace0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2acf0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2ad00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2ad10 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2ad20 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ad30 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2ad40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ad50 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2ad60 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2ad70 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2ad80 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2ad90 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2ada0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2adb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2adc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2add0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2ade0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2adf0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2ae00 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2ae10 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2ae20 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2ae30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2ae40 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2ae50 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2ae60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ae70 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2ae80 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2ae90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2aea0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2aeb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2aec0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2aed0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2aee0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2aef0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2af00 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2af10 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2af20 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2af30 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2af40 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2af50 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2af60 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2af70 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2af80 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2af90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2afa0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2afb0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2afc0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2afd0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2afe0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2aff0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2b000 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2b010 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2b020 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2b030 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2b040 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2b050 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2b060 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2b070 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2b080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b090 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2b0a0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2b0b0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2b0c0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2b0d0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2b0e0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2b0f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2b100 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2b110 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b120 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2b130 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2b140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b150 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2b160 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2b170 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b180 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2b190 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b1a0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2b1b0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2b1c0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2b1d0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2b1e0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2b1f0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2b200 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2b210 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2b220 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2b230 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2b240 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2b250 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2b260 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2b270 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2b280 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2b290 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2b2a0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2b2b0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2b2c0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2b2d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2b2e0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2b2f0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2b300 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2b310 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2b320 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2b330 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2b340 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2b350 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2b360 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2b370 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2b380 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2b390 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2b3a0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2b3b0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2b3c0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2b3d0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2b3e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2b3f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2b400 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2b410 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2b420 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2b430 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2b440 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2b450 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2b460 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2b470 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2b480 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2b490 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2b4a0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2b4b0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2b4c0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2b4d0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2b4e0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2b4f0 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2b500 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2b510 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2b520 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2b530 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2b540 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2b550 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2b560 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2b570 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2b580 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2b590 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2b5a0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2b5b0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2b5c0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2b5d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b5e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2b5f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2b600 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2b610 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2b620 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2b630 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2b640 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2b650 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2b660 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b670 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2b680 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2b690 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2b6a0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2b6b0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2b6c0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2b6d0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2b6e0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2b6f0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2b700 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b710 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2b720 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2b730 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2b740 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2b750 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2b760 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2b770 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2b780 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2b790 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2b7a0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2b7b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b7c0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2b7d0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2b7e0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2b7f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b800 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2b810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2b820 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2b830 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2b840 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2b850 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2b860 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2b870 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2b880 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2b890 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b8a0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b8b0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2b8c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b8d0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2b8e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2b8f0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2b900 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2b910 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2b920 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2b930 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2b940 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2b950 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2b960 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2b970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b980 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2b990 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2b9a0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2b9b0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2b9c0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2b9d0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2b9e0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2b9f0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2ba00 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2ba10 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2ba20 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2ba30 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2ba40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2ba50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ba60 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2ba70 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2ba80 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2ba90 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2baa0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2bab0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2bac0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2bad0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2bae0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2baf0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2bb00 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2bb10 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2bb20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2bb30 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2bb40 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2bb50 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2bb60 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2bb70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bb80 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2bb90 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2bba0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2bbb0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2bbc0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2bbd0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2bbe0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2bbf0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2bc00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2bc10 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2bc20 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2bc30 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2bc40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2bc50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bc60 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2bc70 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2bc80 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2bc90 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2bca0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2bcb0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2bcc0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2bcd0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2bce0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2bcf0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2bd00 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2bd10 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2bd20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2bd30 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2bd40 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2bd50 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2bd60 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2bd70 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2bd80 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2bd90 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2bda0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2bdb0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2bdc0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2bdd0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2bde0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2bdf0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2be00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2be10 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2be20 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2be30 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2be40 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2be50 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2be60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2be70 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2be80 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2be90 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2bea0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2beb0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2bec0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2bed0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2bee0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2bef0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2bf00 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2bf10 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2bf20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2bf30 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2bf40 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2bf50 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2bf60 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2bf70 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2bf80 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2bf90 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2bfa0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bfb0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2bfc0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2bfd0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2bfe0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2bff0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2c000 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2c010 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2c020 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2c030 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2c040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c050 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2c060 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2c070 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2c080 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2c090 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2c0a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
2c0b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c0c0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2c0d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2c0e0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2c0f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2c100 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2c110 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2c120 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2c130 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2c140 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2c150 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2c160 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2c170 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2c180 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2c190 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2c1a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2c1b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2c1c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2c1d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2c1e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2c1f0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2c200 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2c210 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2c220 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2c230 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2c240 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c250 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c260 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2c270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2c280 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2c290 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2c2a0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2c2b0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2c2c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c2d0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
2c2e0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2c2f0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2c300 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2c310 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2c320 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2c330 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2c340 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c350 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c360 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c370 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2c380 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2c390 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2c3a0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2c3b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2c3c0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2c3d0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
2c3e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2c3f0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
2c400 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c410 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2c420 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2c430 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2c440 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2c450 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2c460 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2c470 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2c480 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2c490 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2c4a0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2c4b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2c4c0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2c4d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2c4e0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2c4f0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2c500 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2c510 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2c520 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2c530 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2c540 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2c550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c560 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2c570 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2c580 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c590 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2c5a0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
2c5b0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
2c5c0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
2c5d0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2c5e0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
2c5f0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
2c600 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
2c610 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2c620 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
2c630 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
2c640 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2c650 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
2c660 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
2c670 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2c680 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
2c690 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
2c6a0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
2c6b0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
2c6c0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
2c6d0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
2c6e0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
2c6f0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
2c700 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
2c710 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
2c720 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
2c730 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
2c740 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2c750 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2c760 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2c770 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
2c780 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2c790 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2c7a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2c7b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2c7c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
2c7d0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
2c7e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
2c7f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2c800 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2c810 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2c820 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2c830 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2c840 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
2c850 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2c860 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2c870 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2c880 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2c890 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2c8a0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2c8b0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2c8c0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
2c8d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c8e0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2c8f0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2c900 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
2c910 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2c920 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2c930 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2c940 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2c950 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2c960 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2c970 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2c980 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2c990 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2c9a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2c9b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2c9c0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2c9d0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2c9e0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2c9f0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2ca00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2ca10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2ca20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2ca30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2ca40 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2ca50 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2ca60 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2ca70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ca80 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
2ca90 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2caa0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2cab0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2cac0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2cad0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2cae0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2caf0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2cb00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cb10 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2cb20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2cb30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2cb40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cb50 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2cb60 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2cb70 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2cb80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2cb90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2cba0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2cbb0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2cbc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cbd0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2cbe0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2cbf0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2cc00 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2cc10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2cc20 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2cc30 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2cc40 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
2cc50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2cc60 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2cc70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2cc80 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2cc90 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2cca0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2ccb0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2ccc0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2ccd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cce0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2ccf0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2cd00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2cd10 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2cd20 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2cd30 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2cd40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cd50 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2cd60 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2cd70 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2cd80 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2cd90 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2cda0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
2cdb0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2cdc0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2cdd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cde0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2cdf0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2ce00 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2ce10 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2ce20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2ce30 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2ce40 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
2ce50 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2ce60 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2ce70 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2ce80 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2ce90 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2cea0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2ceb0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2cec0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2ced0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2cee0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2cef0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2cf00 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2cf10 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2cf20 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2cf30 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2cf40 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2cf50 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2cf60 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2cf70 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2cf80 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2cf90 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2cfa0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2cfb0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2cfc0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2cfd0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2cfe0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2cff0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2d000 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2d010 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2d020 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2d030 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2d040 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2d050 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2d060 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2d070 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2d080 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d090 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d0a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d0b0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2d0c0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2d0d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2d0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2d0f0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2d100 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2d110 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2d120 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2d130 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2d140 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2d150 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2d160 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2d170 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2d180 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2d190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2d1a0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2d1b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2d1c0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
2d1d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d1e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2d1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d200 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2d210 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2d220 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2d230 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d240 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2d250 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2d260 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2d270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2d290 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2d2a0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2d2b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2d2c0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2d2d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2d2e0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2d2f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d300 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2d310 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2d320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d330 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2d340 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2d350 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2d360 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2d370 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2d380 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2d390 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2d3a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2d3b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2d3c0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2d3d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2d3e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2d3f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2d400 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2d410 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2d420 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2d430 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2d440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2d450 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2d460 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2d470 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2d480 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2d490 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2d4a0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2d4b0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2d4c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2d4d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2d4e0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2d4f0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2d500 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2d510 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2d520 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2d530 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2d540 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2d550 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2d560 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2d570 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2d580 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2d590 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2d5a0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2d5b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d5c0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2d5d0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2d5e0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2d5f0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2d600 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2d610 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2d620 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2d630 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2d640 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2d650 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2d660 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2d670 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2d680 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2d690 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2d6a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2d6b0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2d6c0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2d6d0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2d6e0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2d6f0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2d700 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2d710 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2d720 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2d730 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2d740 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2d750 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2d760 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2d770 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d780 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2d790 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2d7a0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2d7b0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2d7c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d7d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d7e0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2d7f0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2d800 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2d810 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2d820 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2d830 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2d840 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2d850 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2d860 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2d870 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2d880 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d890 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2d8a0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2d8b0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2d8c0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2d8d0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2d8e0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2d8f0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2d900 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2d910 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d920 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2d930 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2d940 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2d950 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2d960 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2d970 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2d980 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2d990 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2d9a0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2d9b0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2d9c0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2d9d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2d9e0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2d9f0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2da00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2da10 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2da20 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2da30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2da40 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2da50 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2da60 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2da70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2da80 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2da90 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2daa0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2dab0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2dac0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2dad0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2dae0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2daf0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2db00 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2db10 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2db20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2db30 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2db40 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2db50 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2db60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2db70 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2db80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2db90 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2dba0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2dbb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2dbc0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2dbd0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2dbe0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2dbf0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2dc00 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2dc10 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2dc20 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2dc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dc40 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2dc50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2dc60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2dc70 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2dc80 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2dc90 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2dca0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2dcb0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2dcc0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2dcd0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2dce0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2dcf0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2dd00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dd10 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2dd20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2dd30 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2dd40 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2dd50 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2dd60 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2dd70 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2dd80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
2dd90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2dda0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2ddb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ddc0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2ddd0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2dde0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ddf0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2de00 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2de10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2de20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2de30 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2de40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2de50 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2de60 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2de70 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2de80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2de90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2dea0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2deb0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2dec0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2ded0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2dee0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2def0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2df00 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
2df10 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
2df20 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
2df30 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
2df40 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
2df50 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
2df60 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
2df70 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
2df80 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
2df90 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
2dfa0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
2dfb0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
2dfc0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
2dfd0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
2dfe0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
2dff0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
2e000 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
2e010 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2e020 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2e030 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2e040 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2e050 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2e060 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2e070 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2e080 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2e090 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2e0a0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2e0b0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2e0c0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2e0d0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2e0e0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2e0f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2e100 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2e110 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2e120 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2e130 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2e140 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2e150 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2e160 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2e170 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2e180 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2e190 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2e1a0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2e1b0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2e1c0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2e1d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2e1e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2e1f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e200 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2e210 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
2e220 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
2e230 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2e240 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
2e250 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
2e260 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
2e270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2e280 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e290 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
2e2a0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
2e2b0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
2e2c0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
2e2d0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
2e2e0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
2e2f0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
2e300 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
2e310 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
2e320 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2e330 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
2e340 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e350 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
2e360 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e380 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2e390 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2e3a0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
2e3b0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
2e3c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
2e3d0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
2e3e0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2e3f0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2e400 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e410 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2e420 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2e430 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2e440 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2e450 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2e460 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2e470 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2e480 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
2e490 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2e4a0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2e4b0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2e4c0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
2e4d0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
2e4e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
2e4f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
2e500 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
2e510 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
2e520 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
2e530 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2e540 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2e550 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
2e560 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
2e570 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
2e580 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
2e590 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
2e5a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
2e5b0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
2e5c0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
2e5d0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2e5e0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2e5f0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
2e600 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
2e610 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
2e620 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
2e630 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
2e640 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
2e650 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
2e660 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
2e670 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
2e680 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
2e690 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
2e6a0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
2e6b0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
2e6c0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
2e6d0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
2e6e0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
2e6f0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
2e700 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e710 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2e720 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2e730 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2e740 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2e750 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2e760 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
2e770 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e780 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e790 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2e7a0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
2e7b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2e7c0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
2e7d0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
2e7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e7f0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
2e800 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
2e810 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
2e820 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
2e830 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
2e840 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2e850 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2e860 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2e870 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2e880 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2e890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2e8a0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
2e8b0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
2e8c0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
2e8d0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
2e8e0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2e8f0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
2e900 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
2e910 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
2e920 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
2e930 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
2e940 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
2e950 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
2e960 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
2e970 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
2e980 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
2e990 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
2e9a0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
2e9b0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
2e9c0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2e9d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
2e9e0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
2e9f0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
2ea00 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
2ea10 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
2ea20 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
2ea30 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
2ea40 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
2ea50 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
2ea60 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
2ea70 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
2ea80 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
2ea90 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2eaa0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
2eab0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2eac0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
2ead0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
2eae0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
2eaf0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
2eb00 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
2eb10 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
2eb20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
2eb30 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
2eb40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2eb50 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
2eb60 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
2eb70 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
2eb80 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
2eb90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2eba0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
2ebb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ebc0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2ebd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ebe0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2ebf0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
2ec00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2ec10 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2ec20 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
2ec30 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
2ec40 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
2ec50 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
2ec60 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
2ec70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
2ec80 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
2ec90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2eca0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
2ecb0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
2ecc0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
2ecd0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
2ece0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2ecf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ed00 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2ed10 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2ed20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2ed30 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2ed40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ed50 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2ed60 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2ed70 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2ed80 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2ed90 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2eda0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2edb0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2edc0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2edd0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2ede0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2edf0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
2ee00 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
2ee10 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2ee20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ee30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ee40 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
2ee50 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
2ee60 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
2ee70 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
2ee80 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
2ee90 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
2eea0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2eeb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2eec0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2eed0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2eee0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2eef0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ef00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2ef10 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2ef20 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2ef30 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2ef40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2ef50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2ef60 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2ef70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2ef80 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
2ef90 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
2efa0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
2efb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
2efc0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
2efd0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2efe0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
2eff0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
2f000 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2f010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f020 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
2f030 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f040 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
2f050 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
2f060 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
2f070 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2f080 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f090 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2f0a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f0b0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
2f0c0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
2f0d0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
2f0e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2f0f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
2f100 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2f110 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2f120 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2f130 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f140 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f150 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f160 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f170 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
2f180 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2f190 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
2f1a0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
2f1b0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2f1c0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2f1d0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2f1e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f1f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2f200 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
2f210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f220 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
2f230 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
2f240 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
2f250 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
2f260 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2f270 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2f280 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
2f290 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
2f2a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2f2b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2f2c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f2d0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
2f2e0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
2f2f0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2f300 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2f310 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2f320 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2f330 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2f340 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2f350 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2f360 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2f370 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2f380 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2f390 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f3a0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
2f3b0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
2f3c0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
2f3d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
2f3e0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
2f3f0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
2f400 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
2f410 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2f420 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2f430 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
2f440 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2f450 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2f460 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f470 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f480 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2f490 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2f4a0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2f4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f4c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
2f4d0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
2f4e0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2f4f0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2f500 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2f510 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
2f520 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
2f530 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
2f540 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f550 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2f560 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2f570 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2f580 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2f590 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
2f5a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2f5b0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
2f5c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f5d0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
2f5e0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2f5f0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2f600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f610 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f620 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
2f630 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2f640 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2f650 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2f660 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
2f670 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2f680 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f690 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2f6a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2f6b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f6c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2f6d0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2f6e0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2f6f0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2f700 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2f710 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f720 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2f730 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f740 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2f750 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f760 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f770 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2f780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f790 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2f7a0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
2f7b0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
2f7c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f7d0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2f7e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f7f0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2f800 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2f810 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2f820 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f830 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f840 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2f850 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2f860 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2f870 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2f880 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2f890 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2f8a0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2f8b0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2f8c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2f8d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
2f8e0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
2f8f0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
2f900 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
2f910 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
2f920 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f930 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2f940 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
2f950 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f960 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f970 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f980 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2f990 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2f9a0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2f9b0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2f9c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2f9d0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2f9e0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2f9f0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2fa00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fa10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fa20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fa30 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2fa40 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2fa50 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2fa60 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2fa70 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2fa80 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2fa90 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2faa0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2fab0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2fac0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2fad0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2fae0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2faf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fb00 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fb10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2fb20 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2fb30 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2fb40 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2fb50 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2fb60 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2fb70 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2fb80 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
2fb90 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2fba0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2fbb0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2fbc0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2fbd0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fbe0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2fbf0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
2fc00 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2fc10 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2fc20 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2fc30 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2fc40 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
2fc50 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2fc60 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2fc70 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
2fc80 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2fc90 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
2fca0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
2fcb0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
2fcc0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
2fcd0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
2fce0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2fcf0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2fd00 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2fd10 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2fd20 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fd30 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2fd40 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2fd50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2fd60 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2fd70 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2fd80 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2fd90 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2fda0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2fdb0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2fdc0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2fdd0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2fde0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2fdf0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2fe00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fe10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2fe20 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2fe30 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2fe40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fe50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2fe60 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2fe70 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2fe80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2fe90 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2fea0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2feb0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2fec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fed0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2fee0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2fef0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2ff00 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2ff10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2ff20 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2ff30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2ff40 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2ff50 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2ff60 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2ff70 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2ff80 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2ff90 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2ffa0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ffb0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2ffc0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2ffd0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2ffe0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2fff0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
30000 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
30010 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
30020 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30030 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
30040 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
30050 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
30060 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30070 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
30080 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
30090 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
300a0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
300b0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
300c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
300d0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
300e0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
300f0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
30100 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
30110 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
30120 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
30130 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
30140 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
30150 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
30160 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30180 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
30190 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
301a0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
301b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
301c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
301d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
301e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
301f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30200 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
30210 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
30220 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30230 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30240 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
30250 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
30260 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30270 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
30280 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
30290 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
302a0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
302b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
302c0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
302d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
302e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
302f0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
30300 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
30310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30320 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
30330 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30340 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
30350 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
30360 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30370 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
30380 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
30390 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
303a0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
303b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
303c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
303d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
303e0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
303f0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
30400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30410 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
30420 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30430 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
30440 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
30450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30460 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
30470 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
30480 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
30490 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
304a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
304b0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
304c0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
304d0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
304e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
304f0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
30500 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
30510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30520 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
30530 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
30540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
30550 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
30560 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
30570 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
30580 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
30590 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
305a0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
305b0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
305c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
305d0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
305e0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
305f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
30600 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
30610 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
30620 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
30630 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
30640 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
30650 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
30660 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
30670 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
30680 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
30690 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
306a0 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
306b0 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
306c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
306d0 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
306e0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
306f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
30700 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
30710 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
30720 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
30730 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
30740 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
30750 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
30760 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
30770 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
30780 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
30790 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
307a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
307b0 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
307c0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
307d0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
307e0 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
307f0 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
30800 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
30810 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
30820 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
30830 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
30840 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
30850 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
30860 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
30870 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
30880 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
30890 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
308a0 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
308b0 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
308c0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
308d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
308e0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
308f0 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
30900 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
30910 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
30920 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
30930 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
30940 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
30950 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
30960 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30970 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
30980 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
30990 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
309a0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
309b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
309c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
309d0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
309e0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
309f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
30a00 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
30a10 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
30a20 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
30a30 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
30a40 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
30a50 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30a60 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
30a70 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
30a80 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
30a90 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
30aa0 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
30ab0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
30ac0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
30ad0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
30ae0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
30af0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
30b00 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
30b10 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
30b20 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
30b30 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
30b40 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30b50 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
30b60 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
30b70 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
30b80 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
30b90 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
30ba0 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
30bb0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
30bc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
30bd0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
30be0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
30bf0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30c00 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
30c10 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
30c20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
30c30 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
30c40 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
30c50 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
30c60 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
30c70 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
30c80 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
30c90 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
30ca0 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
30cb0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
30cc0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
30cd0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
30ce0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
30cf0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
30d00 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
30d10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
30d20 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
30d30 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
30d40 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
30d50 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
30d60 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
30d70 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
30d80 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
30d90 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
30da0 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
30db0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
30dc0 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
30dd0 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
30de0 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
30df0 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
30e00 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
30e10 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
30e20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30e30 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
30e40 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
30e50 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
30e60 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
30e70 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
30e80 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
30e90 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
30ea0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
30eb0 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
30ec0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
30ed0 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
30ee0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
30ef0 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
30f00 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
30f10 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
30f20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
30f30 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
30f40 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
30f50 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
30f60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30f70 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
30f80 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
30f90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
30fa0 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
30fb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
30fc0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
30fd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
30fe0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
30ff0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31000 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
31010 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
31020 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
31030 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
31040 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
31050 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
31060 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
31070 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
31080 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
31090 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
310a0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
310b0 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
310c0 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
310d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
310e0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
310f0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
31100 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
31110 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
31120 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
31130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
31140 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
31150 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
31160 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
31170 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31180 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
31190 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
311a0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
311b0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
311c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
311d0 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
311e0 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
311f0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
31200 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
31210 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
31220 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
31230 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31240 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
31250 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
31260 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
31270 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
31280 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
31290 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
312a0 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
312b0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
312c0 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
312d0 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
312e0 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
312f0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
31300 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
31310 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
31320 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
31330 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
31340 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31350 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
31360 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31370 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
31380 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31390 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
313a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
313b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
313c0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
313d0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
313e0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
313f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
31400 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
31410 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
31420 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31430 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
31440 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
31450 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
31460 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
31470 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
31480 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
31490 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
314a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
314b0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
314c0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
314d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
314e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
314f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
31500 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
31510 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
31520 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
31530 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
31540 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
31550 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
31560 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
31570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31580 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
31590 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
315a0 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
315b0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
315c0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
315d0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
315e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
315f0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
31600 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31610 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
31620 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
31630 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
31640 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
31650 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
31660 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
31670 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
31680 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
31690 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
316a0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
316b0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
316c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
316d0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
316e0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
316f0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
31700 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
31710 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
31720 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
31730 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
31740 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
31750 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
31760 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
31770 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
31780 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
31790 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
317a0 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
317b0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
317c0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
317d0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
317e0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
317f0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
31800 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
31810 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
31820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
31830 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
31840 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
31850 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
31860 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31870 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
31880 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31890 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
318a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
318b0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
318c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
318d0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
318e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
318f0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
31900 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
31910 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
31920 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
31930 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
31940 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
31950 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
31960 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
31970 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
31980 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
31990 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
319a0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
319b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
319c0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
319d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
319e0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
319f0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
31a00 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
31a10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31a20 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
31a30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31a40 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
31a50 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
31a60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31a70 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
31a80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31a90 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
31aa0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
31ab0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
31ac0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
31ad0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
31ae0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31af0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
31b00 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
31b10 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
31b20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
31b30 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
31b40 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
31b50 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
31b60 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
31b70 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
31b80 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
31b90 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
31ba0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
31bb0 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
31bc0 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
31bd0 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
31be0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
31bf0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
31c00 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
31c10 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
31c20 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
31c30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31c40 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
31c50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
31c60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
31c70 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
31c80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
31c90 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
31ca0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
31cb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
31cc0 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
31cd0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
31ce0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
31cf0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
31d00 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
31d10 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
31d20 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
31d30 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
31d40 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
31d50 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
31d60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
31d70 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
31d80 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
31d90 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
31da0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
31db0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
31dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
31dd0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
31de0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
31df0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
31e00 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
31e10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
31e20 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
31e30 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
31e40 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
31e50 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
31e60 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
31e70 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
31e80 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
31e90 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
31ea0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
31eb0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
31ec0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
31ed0 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
31ee0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
31ef0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
31f00 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
31f10 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
31f20 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
31f30 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
31f40 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
31f50 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
31f60 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
31f70 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
31f80 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
31f90 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
31fa0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
31fb0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
31fc0 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
31fd0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
31fe0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
31ff0 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
32000 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
32010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
32020 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
32030 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
32040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
32050 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
32060 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
32070 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
32080 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
32090 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
320a0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
320b0 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
320c0 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
320d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
320e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
320f0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
32100 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
32110 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
32120 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
32130 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
32140 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
32150 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
32160 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
32170 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
32180 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
32190 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
321a0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
321b0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
321c0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
321d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
321e0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
321f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
32200 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
32210 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
32220 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
32230 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
32240 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
32250 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
32260 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
32270 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
32280 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
32290 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
322a0 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
322b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
322c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
322d0 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
322e0 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
322f0 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
32300 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
32310 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  hs..*/.int sqlit
32320 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
32330 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32340 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
32350 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
32360 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
32370 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
32380 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
32390 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
323a0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
323b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
323c0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
323d0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
323e0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
323f0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
32400 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
32410 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
32420 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
32430 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
32440 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
32450 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
32460 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
32470 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
32480 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
32490 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
324a0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
324b0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
324c0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
324d0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
324e0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
324f0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
32500 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
32510 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
32520 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
32530 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
32540 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
32550 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
32560 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
32570 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
32580 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
32590 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
325a0 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
325b0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
325c0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
325d0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
325e0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
325f0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
32600 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
32610 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
32620 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
32630 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
32640 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
32650 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
32660 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
32670 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
32680 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
32690 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
326a0 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
326b0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
326c0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
326d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
326e0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
326f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
32700 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
32710 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
32720 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
32730 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
32740 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
32750 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
32760 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
32770 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
32780 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
32790 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
327a0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
327b0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
327c0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
327d0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
327e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
327f0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
32800 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
32810 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
32820 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
32830 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
32840 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
32850 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
32860 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32870 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
32880 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
32890 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
328a0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
328b0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
328c0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
328d0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
328e0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
328f0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
32900 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
32910 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
32920 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
32930 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
32940 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
32950 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
32960 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
32970 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
32980 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
32990 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
329a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
329b0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
329c0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
329d0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
329e0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
329f0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
32a00 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
32a10 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
32a20 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
32a30 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
32a40 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
32a50 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
32a60 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
32a70 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
32a80 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
32a90 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
32aa0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
32ab0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
32ac0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
32ad0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
32ae0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
32af0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
32b00 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
32b10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
32b20 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
32b30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
32b40 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
32b50 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
32b60 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
32b70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
32b80 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
32b90 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
32ba0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
32bb0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
32bc0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
32bd0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
32be0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
32bf0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
32c00 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
32c10 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
32c20 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
32c30 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
32c40 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
32c50 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
32c60 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
32c70 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
32c80 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
32c90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
32ca0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
32cb0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
32cc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32cd0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
32ce0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
32cf0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
32d00 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
32d10 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
32d20 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
32d30 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
32d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
32d50 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
32d60 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
32d70 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
32d80 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
32d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
32da0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32db0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
32dc0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
32dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32de0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
32df0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
32e00 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
32e10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32e20 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
32e30 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
32e40 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
32e50 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
32e60 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
32e70 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
32e80 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
32e90 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
32ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32eb0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
32ec0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
32ed0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
32ee0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32ef0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
32f00 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
32f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
32f20 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
32f30 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
32f40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32f50 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
32f60 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
32f70 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
32f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32f90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
32fa0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
32fb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
32fc0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
32fd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32fe0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
32ff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33000 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
33010 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
33020 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
33030 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
33040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
33050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33060 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
33070 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33080 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
33090 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
330a0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
330b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
330c0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
330d0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
330e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
330f0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
33100 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
33110 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
33120 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33130 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33140 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
33150 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
33160 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
33170 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
33180 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
33190 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
331a0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
331b0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
331c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
331d0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
331e0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
331f0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
33200 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
33210 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
33220 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
33230 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
33240 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
33250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33260 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
33270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33280 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
33290 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
332a0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
332b0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
332c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
332d0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
332e0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
332f0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
33300 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
33310 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
33320 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33330 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
33340 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
33350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33360 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
33370 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
33380 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
33390 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
333a0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
333b0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
333c0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
333d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
333e0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
333f0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
33400 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
33410 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
33420 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33430 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
33440 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
33450 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
33460 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
33470 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
33480 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
33490 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
334a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
334b0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
334c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
334d0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
334e0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
334f0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
33500 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
33510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
33520 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
33530 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
33540 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
33550 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
33560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33570 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
33580 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
33590 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
335a0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
335b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
335c0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
335d0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
335e0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
335f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
33600 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
33610 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
33620 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
33630 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
33640 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
33650 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
33660 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33670 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33680 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
33690 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
336a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
336b0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
336c0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
336d0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
336e0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
336f0 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
33700 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
33710 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33720 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
33730 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
33740 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33750 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
33760 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
33770 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
33780 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
33790 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
337a0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
337b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
337c0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
337d0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
337e0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
337f0 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
33800 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
33810 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
33820 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
33830 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
33840 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
33850 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
33860 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
33870 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
33880 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
33890 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
338a0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
338b0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
338c0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
338d0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
338e0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
338f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
33900 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
33910 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
33920 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
33930 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
33940 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
33950 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
33960 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
33970 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
33980 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
33990 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
339a0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
339b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
339c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
339d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
339e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
339f0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
33a00 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
33a10 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
33a20 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
33a30 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
33a40 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
33a50 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33a60 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
33a70 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
33a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33a90 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
33aa0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
33ab0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
33ac0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
33ad0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
33ae0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
33af0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
33b00 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
33b10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33b20 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
33b30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33b40 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
33b50 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
33b60 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
33b70 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
33b80 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
33b90 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
33ba0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
33bb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
33bc0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
33bd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33be0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
33bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
33c00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
33c10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
33c20 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
33c30 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
33c40 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
33c50 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
33c60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
33c70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
33c80 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
33c90 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
33ca0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
33cb0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
33cc0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
33cd0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
33ce0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
33cf0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
33d00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
33d10 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
33d20 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
33d30 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
33d40 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
33d50 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
33d60 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
33d70 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
33d80 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
33d90 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
33da0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
33db0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
33dc0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
33dd0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
33de0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
33df0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
33e00 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
33e10 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
33e20 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
33e30 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
33e40 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
33e50 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
33e60 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
33e70 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
33e80 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
33e90 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
33ea0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
33eb0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
33ec0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
33ed0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
33ee0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
33ef0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
33f00 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
33f10 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
33f20 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
33f30 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
33f40 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
33f50 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
33f60 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
33f70 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
33f80 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
33f90 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
33fa0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
33fb0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
33fc0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
33fd0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
33fe0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
33ff0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
34000 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
34010 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
34020 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
34030 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
34040 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
34050 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
34060 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
34070 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
34080 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
34090 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
340a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
340b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
340c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
340d0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
340e0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
340f0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
34100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34110 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
34120 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
34130 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
34140 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34150 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
34160 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
34170 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
34180 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
34190 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
341a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
341b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
341c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
341d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
341e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
341f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
34200 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
34210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34220 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
34230 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
34240 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
34250 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
34260 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
34270 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
34280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34290 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
342a0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
342b0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
342c0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
342d0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
342e0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
342f0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
34300 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
34310 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
34320 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
34330 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34340 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
34350 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
34360 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
34370 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
34380 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
34390 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
343a0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
343b0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
343c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
343d0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
343e0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
343f0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
34400 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
34410 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
34420 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
34430 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
34440 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
34450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34460 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
34470 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
34480 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
34490 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
344a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
344b0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
344c0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
344d0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
344e0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
344f0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
34500 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
34510 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
34520 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
34530 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
34540 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
34550 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
34560 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
34570 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
34580 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
34590 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
345a0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
345b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
345c0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
345d0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
345e0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
345f0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
34600 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
34610 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
34620 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
34630 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
34640 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
34650 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
34660 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
34670 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
34680 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
34690 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
346a0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
346b0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
346c0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
346d0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
346e0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
346f0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
34700 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
34710 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
34720 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
34730 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
34740 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
34750 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
34760 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
34770 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
34780 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
34790 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
347a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
347b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
347c0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
347d0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
347e0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
347f0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
34800 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
34810 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
34820 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
34830 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
34840 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
34850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34860 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
34870 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
34880 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34890 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
348a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
348b0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
348c0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
348d0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
348e0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
348f0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
34900 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
34910 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
34920 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
34930 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
34940 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
34950 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
34960 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
34970 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
34980 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
34990 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
349a0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
349b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
349c0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
349d0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
349e0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
349f0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
34a00 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
34a10 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
34a20 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
34a30 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  y() routine is a
34a40 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67   no-op returning
34a50 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69   zero.** if SQLi
34a60 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c  te is not compil
34a70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
34a80 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
34a90 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e  NAGEMENT]..*/.in
34aa0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
34ab0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
34ac0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ad0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
34ae0 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
34af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
34b00 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
34b10 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34b20 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73  s and/or queries
34b30 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d   the.** soft lim
34b40 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
34b50 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
34b60 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
34b70 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
34b80 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69  .** ^SQLite stri
34b90 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70  ves to keep heap
34ba0 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74   memory utilizat
34bb0 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  ion below the so
34bc0 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74  ft heap.** limit
34bd0 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65   by reducing the
34be0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
34bf0 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67   held in the pag
34c00 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65  e cache.** as he
34c10 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73  ap memory usages
34c20 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20   approaches the 
34c30 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  limit..** ^The s
34c40 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
34c50 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  s "soft" because
34c60 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c   even though SQL
34c70 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73  ite strives to s
34c80 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65  tay.** below the
34c90 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20   limit, it will 
34ca0 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74  exceed the limit
34cb0 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e   rather than gen
34cc0 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c  erate.** an [SQL
34cd0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72  ITE_NOMEM] error
34ce0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
34cf0 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  s, the soft heap
34d00 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64   limit .** is ad
34d10 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
34d20 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  ** ^The return v
34d30 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
34d40 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34d50 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a  t64() is the siz
34d60 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74  e of.** the soft
34d70 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f   heap limit prio
34d80 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20  r to the call.  
34d90 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
34da0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
34db0 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  * then no change
34dc0 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20   is made to the 
34dd0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
34de0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72    Hence, the cur
34df0 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  rent.** size of 
34e00 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34e10 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  mit can be deter
34e20 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e  mined by invokin
34e30 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66  g.** sqlite3_sof
34e40 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
34e50 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65   with a negative
34e60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
34e70 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
34e80 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e  t N is zero then
34e90 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
34ea0 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64  imit is disabled
34eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f  ..**.** ^(The so
34ec0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
34ed0 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e   not enforced in
34ee0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
34ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
34f00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
34f10 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69   following condi
34f20 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a  tions are true:.
34f30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
34f40 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70  i> The soft heap
34f50 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f   limit is set to
34f60 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d   zero..** <li> M
34f70 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67  emory accounting
34f80 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69   is disabled usi
34f90 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  ng a combination
34fa0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
34fb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
34fc0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
34fd0 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20  MEMSTATUS],...) 
34fe0 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f  start-time optio
34ff0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68  n and.**      th
35000 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  e [SQLITE_DEFAUL
35010 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d  T_MEMSTATUS] com
35020 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
35030 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74  ..** <li> An alt
35040 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61  ernative page ca
35050 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
35060 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20  on is specified 
35070 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73  using.**      [s
35080 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
35090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
350a0 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c  ACHE],...)..** <
350b0 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63  li> The page cac
350c0 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f  he allocates fro
350d0 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  m its own memory
350e0 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a   pool supplied.*
350f0 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74  *      by [sqlit
35100 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
35110 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
35120 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72  CHE],...) rather
35130 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72   than.**      fr
35140 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20  om the heap..** 
35150 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65  </ul>)^.**.** Be
35160 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
35170 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
35180 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  3, the soft heap
35190 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
351a0 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ed.** regardless
351b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
351c0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ot the [SQLITE_E
351d0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
351e0 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70  AGEMENT].** comp
351f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
35200 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74  is invoked.  Wit
35210 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
35220 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
35230 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74  NT],.** the soft
35240 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
35250 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79  nforced on every
35260 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35270 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20  on.  Without.** 
35280 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
35290 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
352a0 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ], the soft heap
352b0 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65   limit is only e
352c0 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20  nforced.** when 
352d0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
352e0 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ted by the page 
352f0 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20  cache.  Testing 
35300 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65  suggests that be
35310 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67  cause.** the pag
35320 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70  e cache is the p
35330 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72  redominate memor
35340 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65  y user in SQLite
35350 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  , most.** applic
35360 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69  ations will achi
35370 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66  eve adequate sof
35380 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66  t heap limit enf
35390 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74  orcement without
353a0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b  .** the use of [
353b0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
353c0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
353d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63  ..**.** The circ
353e0 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20  umstances under 
353f0 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c  which SQLite wil
35400 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f  l enforce the so
35410 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61  ft heap limit ma
35420 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  y.** changes in 
35430 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
35440 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71  of SQLite..*/.sq
35450 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
35460 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
35470 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e  mit64(sqlite3_in
35480 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t64 N);../*.** C
35490 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
354a0 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69  ted Soft Heap Li
354b0 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  mit Interface.**
354c0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
354d0 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72  * This is a depr
354e0 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f  ecated version o
354f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
35500 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
35510 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
35520 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
35530 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
35540 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
35550 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79  tibility.** only
35560 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69  .  All new appli
35570 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75  cations should u
35580 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
35590 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
355a0 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63  it64()] interfac
355b0 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68  e rather than th
355c0 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54  is one..*/.SQLIT
355d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
355e0 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
355f0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29  eap_limit(int N)
35600 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
35610 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
35620 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
35630 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
35640 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
35650 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
35660 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
35670 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
35680 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
35690 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
356a0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
356b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
356c0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
356d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
356e0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
356f0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
35700 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
35710 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
35720 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
35730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35740 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
35750 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
35760 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
35770 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
35780 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35790 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
357a0 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
357b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
357c0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
357d0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
357e0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
357f0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
35800 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
35810 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
35820 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
35830 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
35840 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
35850 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
35860 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
35870 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
35880 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
35890 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
358a0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
358b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
358c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
358d0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
358e0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
358f0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
35900 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
35910 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
35920 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
35930 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
35940 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
35950 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
35960 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
35970 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
35980 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
35990 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
359a0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
359b0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
359c0 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
359d0 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
359e0 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
359f0 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
35a00 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
35a10 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
35a20 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
35a30 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
35a40 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
35a50 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
35a60 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
35a70 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
35a80 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
35a90 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
35aa0 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
35ab0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
35ac0 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
35ad0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
35ae0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
35af0 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
35b00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
35b10 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
35b20 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
35b30 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
35b40 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
35b50 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
35b60 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
35b70 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
35b80 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
35b90 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
35ba0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
35bb0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
35bc0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
35bd0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
35be0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
35bf0 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
35c00 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
35c10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
35c20 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
35c30 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
35c40 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
35c50 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
35c60 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
35c70 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
35c80 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
35c90 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
35ca0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
35cb0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
35cc0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
35cd0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
35ce0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
35cf0 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
35d00 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
35d10 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
35d20 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
35d30 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
35d40 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
35d50 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
35d60 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
35d70 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
35d80 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
35d90 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
35da0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
35db0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
35dc0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
35dd0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
35de0 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
35df0 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
35e00 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
35e10 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
35e20 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
35e30 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
35e40 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
35e50 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
35e60 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
35e70 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
35e80 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
35e90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
35ea0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
35eb0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
35ec0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
35ed0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
35ee0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
35ef0 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
35f00 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
35f10 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
35f20 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
35f30 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
35f40 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
35f50 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
35f60 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
35f70 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
35f80 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
35f90 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
35fa0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
35fb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
35fc0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
35fd0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
35fe0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35ff0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
36000 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
36010 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
36020 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
36030 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
36040 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
36050 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
36060 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
36070 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
36080 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
36090 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
360a0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
360b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
360c0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
360d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
360e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
360f0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
36100 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
36110 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36120 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36130 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
36140 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36150 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
36160 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
36170 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36180 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
36190 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
361a0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
361b0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
361c0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
361d0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
361e0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
361f0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
36200 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
36210 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
36220 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
36230 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
36240 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
36250 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
36260 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
36270 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
36280 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
36290 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
362a0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
362b0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
362c0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
362d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
362e0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
362f0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
36300 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
36310 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
36320 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
36330 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
36340 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
36350 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
36360 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
36370 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
36380 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36390 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
363a0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
363b0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
363c0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
363d0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
363e0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
363f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
36400 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
36410 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
36420 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
36430 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
36440 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
36450 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
36460 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
36470 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
36480 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36490 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
364a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
364b0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
364c0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
364d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
364e0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
364f0 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
36500 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
36510 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
36520 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
36530 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
36540 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
36550 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
36560 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
36570 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
36580 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
36590 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
365a0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
365b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
365c0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
365d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
365e0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
365f0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
36600 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
36610 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
36620 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
36630 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
36640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
36650 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
36660 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
36670 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
36680 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
36690 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
366a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
366b0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
366c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
366d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
366e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
366f0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
36700 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36710 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
36720 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
36730 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
36740 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
36750 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
36760 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36770 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
36780 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
36790 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
367a0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
367b0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
367c0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
367d0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
367e0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
367f0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
36800 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
36810 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
36820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
36830 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
36840 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
36850 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
36860 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
36870 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
36880 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
36890 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
368a0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
368b0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
368c0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
368d0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
368e0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
368f0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
36900 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
36910 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
36920 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
36930 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
36940 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
36950 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
36960 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
36970 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
36980 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
36990 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
369a0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
369b0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
369c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
369d0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
369e0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
369f0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
36a00 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
36a10 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
36a20 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
36a30 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
36a40 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
36a50 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
36a60 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
36a70 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
36a80 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
36a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36aa0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
36ab0 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20  Load Statically 
36ac0 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e  Linked Extension
36ad0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  s.**.** ^This in
36ae0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
36af0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
36b00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36b10 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65  invoked for.** e
36b20 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
36b30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
36b40 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  at is created.  
36b50 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73  The idea here is
36b60 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50   that.** xEntryP
36b70 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e  oint() is the en
36b80 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20  try point for a 
36b90 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
36ba0 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  d SQLite extensi
36bb0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f  on.** that is to
36bc0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
36bd0 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c  y loaded into al
36be0 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
36bf0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
36c00 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20  * ^(Even though 
36c10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f  the function pro
36c20 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61  totype shows tha
36c30 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  t xEntryPoint() 
36c40 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75  takes.** no argu
36c50 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e  ments and return
36c60 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69  s void, SQLite i
36c70 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69  nvokes xEntryPoi
36c80 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a  nt() with three.
36c90 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64  ** arguments and
36ca0 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74   expects and int
36cb0 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69  eger result as i
36cc0 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20  f the signature 
36cd0 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20  of the.** entry 
36ce0 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66  point where as f
36cf0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
36d00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
36d10 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78  ** &nbsp;  int x
36d20 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26  EntryPoint(.** &
36d30 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33  nbsp;    sqlite3
36d40 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20   *db,.** &nbsp; 
36d50 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a     const char **
36d60 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62  pzErrMsg,.** &nb
36d70 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72  sp;    const str
36d80 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
36d90 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b  routines *pThunk
36da0 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a  .** &nbsp;  );.*
36db0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
36dc0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66  uote>)^.**.** If
36dd0 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
36de0 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74   routine encount
36df0 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74  ers an error, it
36e00 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a   should make *pz
36e10 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20  ErrMsg.** point 
36e20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  to an appropriat
36e30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
36e40 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b  (obtained from [
36e50 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36e60 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72  )]).** and retur
36e70 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
36e80 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20   [error code].  
36e90 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20  ^SQLite ensures 
36ea0 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a  that *pzErrMsg.*
36eb0 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65  * is NULL before
36ec0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e   calling the xEn
36ed0 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51  tryPoint().  ^SQ
36ee0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
36ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
36f00 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73  e()] on *pzErrMs
36f10 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f  g after xEntryPo
36f20 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20  int() returns.  
36f30 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72  ^If any.** xEntr
36f40 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
36f50 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b   an error, the [
36f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
36f70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
36f80 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
36f90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63  te3_open_v2()] c
36fa0 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  all that provoke
36fb0 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  d the xEntryPoin
36fc0 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a  t() will fail..*
36fd0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
36fe0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
36ff0 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20  sion(X) with an 
37000 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68  entry point X th
37010 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a  at is already.**
37020 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20   on the list of 
37030 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
37040 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65  ions is a harmle
37050 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e  ss no-op. ^No en
37060 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c  try point.** wil
37070 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65  l be called more
37080 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65   than once for e
37090 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
370a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  nection that is 
370b0 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  opened..**.** Se
370c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
370d0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
370e0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  nsion()]..*/.int
370f0 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
37100 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78  tension(void (*x
37110 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64  EntryPoint)(void
37120 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ));../*.** CAPI3
37130 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d  REF: Reset Autom
37140 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c  atic Extension L
37150 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68  oading.**.** ^Th
37160 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73  is interface dis
37170 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61  ables all automa
37180 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70  tic extensions p
37190 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67  reviously.** reg
371a0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
371b0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
371c0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  nsion()]..*/.voi
371d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
371e0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
371f0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
37200 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
37210 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
37220 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
37230 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
37240 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
37250 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
37260 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
37270 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
37280 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
37290 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
372a0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
372b0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
372c0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
372d0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
372e0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
372f0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
37300 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
37310 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
37320 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
37330 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
37340 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
37350 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
37360 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
37370 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
37380 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
37390 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
373a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
373b0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
373c0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
373d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
373e0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
373f0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
37400 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37410 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
37420 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
37430 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
37440 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
37450 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
37460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37470 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
37480 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
37490 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
374a0 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
374b0 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
374c0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
374d0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
374e0 64 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  d a "virtual tab
374f0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
37500 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
37510 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
37520 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
37530 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
37540 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
37550 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
37560 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
37570 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
37580 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
37590 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
375a0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
375b0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
375c0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
375d0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
375e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
375f0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
37600 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37610 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
37620 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
37630 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
37640 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
37650 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
37660 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
37670 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
37680 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
37690 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
376a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
376b0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
376c0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
376d0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
376e0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
376f0 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
37700 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
37710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
37720 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37730 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
37740 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
37750 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
37760 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
37770 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
37780 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
37790 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
377a0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
377b0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
377c0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
377d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
377e0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
377f0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
37800 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
37810 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
37820 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
37830 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
37840 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
37850 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
37860 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
37870 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37880 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
37890 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
378a0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
378b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
378c0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
378d0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
378e0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
378f0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
37900 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
37910 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
37920 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
37930 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
37940 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
37950 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
37960 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
37970 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
37980 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
37990 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
379a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
379b0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
379c0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
379d0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
379e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
379f0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
37a00 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
37a10 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
37a20 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
37a30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37a40 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
37a50 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
37a60 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
37a70 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
37a80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
37a90 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
37aa0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
37ab0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
37ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
37ad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
37ae0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
37af0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
37b00 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
37b10 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
37b20 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37b30 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
37b40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37b50 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
37b60 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
37b70 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37b80 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
37b90 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
37ba0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
37bb0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
37bc0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
37bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37be0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
37bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
37c00 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
37c10 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
37c20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37c30 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
37c40 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
37c50 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
37c60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
37c70 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74  w);.  /* The met
37c80 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
37c90 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
37ca0 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65  he sqlite_module
37cb0 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a   object. Those .
37cc0 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66    ** below are f
37cd0 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  or version 2 and
37ce0 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69   greater. */.  i
37cf0 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29  nt (*xSavepoint)
37d00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37d10 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  VTab, int);.  in
37d20 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71  t (*xRelease)(sq
37d30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37d40 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  b, int);.  int (
37d50 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71  *xRollbackTo)(sq
37d60 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37d70 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a  b, int);.};../*.
37d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
37d90 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
37da0 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
37db0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
37dc0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
37dd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37de0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
37df0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
37e00 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
37e10 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
37e20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
37e30 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
37e40 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
37e50 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
37e60 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
37e70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
37e80 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
37e90 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
37ea0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
37eb0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
37ec0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
37ed0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
37ee0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
37ef0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
37f00 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
37f10 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
37f20 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
37f30 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
37f40 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
37f50 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
37f60 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
37f70 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
37f80 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
37f90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
37fa0 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
37fb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
37fc0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
37fd0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
37fe0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
37ff0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
38000 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
38010 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
38020 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
38030 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
38040 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
38050 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
38060 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
38070 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
38080 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
38090 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
380a0 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
380b0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
380c0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
380d0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
380e0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
380f0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
38100 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
38110 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
38120 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
38130 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
38140 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
38150 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
38160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
38170 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
38180 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
38190 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
381a0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
381b0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
381c0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
381d0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
381e0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
381f0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
38200 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
38210 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
38220 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
38230 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
38240 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
38250 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
38260 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
38270 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
38280 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
38290 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
382a0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
382b0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
382c0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
382d0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
382e0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
382f0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
38300 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
38310 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
38320 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
38330 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
38340 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
38350 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
38360 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
38370 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
38380 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
38390 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
383a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
383b0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
383c0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
383d0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
383e0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
383f0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
38400 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
38410 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
38420 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
38430 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
38440 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
38450 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
38460 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
38470 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
38480 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
38490 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
384a0 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
384b0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
384c0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
384d0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
384e0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
384f0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
38500 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
38510 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
38520 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
38530 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
38540 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
38550 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
38560 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
38570 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
38580 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
38590 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
385a0 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
385b0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
385c0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
385d0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
385e0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
385f0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
38600 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
38610 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
38620 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
38630 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
38640 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
38650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
38660 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
38670 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
38680 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
38690 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
386a0 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
386b0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
386c0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
386d0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
386e0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
386f0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
38700 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
38710 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
38720 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
38730 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
38740 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
38750 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
38760 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
38770 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
38780 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
38790 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
387a0 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
387b0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
387c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
387d0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
387e0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int i